lemon-tls 0.5.5 → 0.7.0

package/src/dtls_socket.js

@@ -52,6 +52,7 @@ function DTLSSocket(udpSocket, options) {
     mtu: options.mtu,
     ticketKeys: options.ticketKeys,
     useCookies: options.useCookies,
+    srtpProfiles: options.srtpProfiles,
   });
 
   // Wire session → UDP
@@ -136,6 +137,11 @@ function DTLSSocket(udpSocket, options) {
     return session.exportKeyingMaterial(length, label, context_value);
   };
 
+  /** Negotiated DTLS-SRTP protection profile (RFC 5764), or null. */
+  self.getSelectedSrtpProfile = function() {
+    return session.getSelectedSrtpProfile();
+  };
+
   /** Peer hello extensions / single extension by numeric type. */
   self.getRemoteExtensions = function() { return session.getRemoteExtensions(); };
   self.getRemoteExtension = function(type) { return session.getRemoteExtension(type); };
@@ -190,6 +196,7 @@ function createDTLSServer(options, connectionListener) {
           mtu: options.mtu,
           ticketKeys: options.ticketKeys,
           useCookies: options.useCookies,
+          srtpProfiles: options.srtpProfiles,
         });
 
         connections[key] = socket;

package/src/record.js

@@ -16,6 +16,7 @@ import {
   w_u8,
   w_u16,
   w_u48,
+  w_u64,
 } from './wire.js';
 
 // ===================== AEAD algorithm resolution =====================
@@ -33,12 +34,12 @@ function getAeadAlgo(cipherSuite) {
 // ===================== TLS 1.3 primitives =====================
 
 /** Derive write key + IV from a TLS 1.3 traffic secret. */
-function deriveKeys(trafficSecret, cipherSuite) {
+function deriveKeys(trafficSecret, cipherSuite, labelPrefix) {
   const empty = new Uint8Array(0);
   let cs = TLS_CIPHER_SUITES[cipherSuite];
   return {
-    key: hkdf_expand_label(cs.hash, trafficSecret, 'key', empty, cs.keylen),
-    iv:  hkdf_expand_label(cs.hash, trafficSecret, 'iv',  empty, 12)
+    key: hkdf_expand_label(cs.hash, trafficSecret, 'key', empty, cs.keylen, labelPrefix),
+    iv:  hkdf_expand_label(cs.hash, trafficSecret, 'iv',  empty, 12, labelPrefix)
   };
 }
 
@@ -589,6 +590,11 @@ function writeRecord(transport, type, payload, version) {
 // readU16, readU48 return value only (no offset tracking), unlike wire.js r_u16 which returns [value, offset]
 
 function readU16(buf, off) { return ((buf[off] << 8) | buf[off+1]) >>> 0; }
+function readU64(buf, off) {
+  let hi = ((buf[off] << 24) | (buf[off+1] << 16) | (buf[off+2] << 8) | buf[off+3]) >>> 0;
+  let lo = ((buf[off+4] << 24) | (buf[off+5] << 16) | (buf[off+6] << 8) | buf[off+7]) >>> 0;
+  return hi * 0x100000000 + lo;
+}
 function readU48(buf, off) {
   let hi = ((buf[off] << 8) | buf[off+1]) >>> 0;
   let lo = ((buf[off+2] << 24) | (buf[off+3] << 16) | (buf[off+4] << 8) | buf[off+5]) >>> 0;
@@ -800,10 +806,35 @@ function isUnifiedHdr(b) { return (b & 0xE0) === UNIFIED_HDR_FIXED; }
  * mask = AES-ECB(snKey, ciphertext[0..15])
  * result = rnBytes XOR mask[0..len-1]
  */
-function maskRecordNumber(snKey, rnBytes, ciphertext) {
-  let sample = new Uint8Array(16);
-  sample.set(ciphertext.subarray(0, Math.min(16, ciphertext.length)), 0);
-  let mask = aesEcbEncrypt(snKey, sample);
+function maskRecordNumber(snKey, rnBytes, ciphertext, algo) {
+  // RFC 9147 §4.2.3: "This procedure requires the ciphertext length to be at
+  // least 16 bytes. Receivers MUST reject shorter records as if they had
+  // failed deprotection." Zero-padding a short sample instead (the previous
+  // behaviour) both diverges from the spec and yields a predictable mask.
+  // Senders must pad short plaintexts; with a 16-byte tag that never happens
+  // for the AEADs we support, so this is a guard, not a code path.
+  if (!ciphertext || ciphertext.length < 16) return null;
+
+  let mask;
+  if (algo === 'chacha20-poly1305') {
+    // Mask = ChaCha20(sn_key, Ciphertext[0..3], Ciphertext[4..15])
+    // — first 4 bytes are the block counter, next 12 the nonce. Node's
+    // 'chacha20' cipher takes exactly that as a 16-byte IV, so the sample is
+    // passed through unchanged and we encrypt a zero block to read off the
+    // keystream.
+    //
+    // The AES branch below is well covered by the DTLS 1.3 suites we
+    // negotiate in practice; this branch is not, so cross-check it against a
+    // BoringSSL peer before trusting it — in particular the counter's byte
+    // order, which the RFC states as a byte range and OpenSSL interprets as a
+    // little-endian u32.
+    let iv = Buffer.from(ciphertext.subarray(0, 16));
+    let c = crypto.createCipheriv('chacha20', snKey, iv);
+    mask = new Uint8Array(c.update(Buffer.alloc(16)));
+  } else {
+    mask = aesEcbEncrypt(snKey, ciphertext.subarray(0, 16));
+  }
+
   let out = new Uint8Array(rnBytes.length);
   for (let i = 0; i < rnBytes.length; i++) out[i] = rnBytes[i] ^ mask[i];
   return out;
@@ -864,7 +895,32 @@ function buildEncryptedDtls13(innerType, plaintext, seq, epoch, keys) {
   ciphertext.set(new Uint8Array(tag), ct.length);
 
   // Encrypt record number
-  let encRn = maskRecordNumber(keys.snKey, rn, ciphertext);
+  let encRn = maskRecordNumber(keys.snKey, rn, ciphertext, algo);
+
+  // ── DIAGNOSTIC (LEMON_DEBUG=1 / WEBRTC_DEBUG=1) ──────────────────────
+  // Everything a peer needs to PARSE this record, printed as we build it.
+  // A decode_error alert means the peer could not make structural sense of
+  // what arrived, so the fields to compare are the info byte (which
+  // declares whether a CID, a length and a 16-bit sequence number are
+  // present), the sequence number before and after masking, and the
+  // declared length against the actual ciphertext size. If two records
+  // are accepted and the third is not, the difference between them shows
+  // up here.
+  try {
+    if (typeof process !== 'undefined' && process.env &&
+        (process.env.LEMON_DEBUG === '1' || process.env.WEBRTC_DEBUG === '1')) {
+      var _h = function (b) { return ('0' + (b & 0xFF).toString(16)).slice(-2); };
+      console.log('[lemon-rec] TX info=0x' + _h(info) +
+        ' [C=' + ((info >> 4) & 1) + ' S=' + ((info >> 3) & 1) +
+        ' L=' + ((info >> 2) & 1) + ' epoch=' + (info & 0x03) + ']' +
+        ' seqPlain=' + _h(rn[0]) + _h(rn[1]) +
+        ' seqMasked=' + _h(encRn[0]) + _h(encRn[1]) +
+        ' declaredLen=' + ciphertext.length +
+        ' aadLen=' + (aad ? aad.length : 'null') +
+        ' snKey=' + (keys.snKey ? 'set' : 'MISSING'));
+    }
+  } catch (_e) {}
+  // ─────────────────────────────────────────────────────────────────────
 
   // Assemble: info(1) + encrypted_rn(2) + length(2) + ciphertext
   let record = new Uint8Array(5 + ciphertext.length);
@@ -909,13 +965,46 @@ function reconstructDtlsSeq(truncated, bits, maxSeq) {
 }
 
 
+/**
+ * Resolve the full epoch from the 2 bits carried in the unified header.
+ *
+ * RFC 9147 §4.2.2: the header holds only the low 2 bits of the epoch, so
+ * epoch 4 is indistinguishable from epoch 0 on the wire, 5 from 1, and so on.
+ * The spec's rule is to use "the most recent past epoch which has matching
+ * bits" — i.e. among the epochs we actually hold read keys for, the highest
+ * one whose low 2 bits match.
+ *
+ * Until KeyUpdate existed, only epochs 0/2/3 were ever in play and each had a
+ * unique bit pattern, so indexing the key table directly by the 2 bits worked
+ * by accident. The first KeyUpdate moves a sender to epoch 4, whose bits are
+ * 00 — and a lookup by bits then hands back the epoch-0 (plaintext) entry.
+ *
+ * @param epochBits    the 2-bit value from the header
+ * @param keysByEpoch  object keyed by FULL epoch number
+ * @returns the full epoch number, or null if we hold no matching keys
+ */
+function resolveReadEpoch(epochBits, keysByEpoch) {
+  if (!keysByEpoch) return null;
+  let best = null;
+  for (let k in keysByEpoch) {
+    if (!Object.prototype.hasOwnProperty.call(keysByEpoch, k)) continue;
+    let e = Number(k);
+    if (!Number.isFinite(e)) continue;
+    if ((e & 0x03) !== (epochBits & 0x03)) continue;
+    if (keysByEpoch[k] == null) continue;
+    if (best === null || e > best) best = e;
+  }
+  return best;
+}
+
+
 /**
  * Decrypt a DTLS 1.3 encrypted record.
  * data: full record bytes (starting with unified header byte)
  * keys: { key, iv, snKey, algo?, maxReadSeq? }
  * Returns { epoch, seq, type, content } or null on failure.
  */
-function decryptEncryptedDtls13(data, keys) {
+function decryptEncryptedDtls13(data, keys, fullEpoch) {
   if (data.length < 1) return null;
 
   let hdr = parseUnifiedHdr(data[0]);
@@ -940,8 +1029,16 @@ function decryptEncryptedDtls13(data, keys) {
   if (off + ctLen > data.length) return null;
   let ciphertext = data.slice(off, off + ctLen);
 
-  // Decrypt record number
-  let rn = maskRecordNumber(keys.snKey, encRn, ciphertext);
+  // Resolve the AEAD before unmasking: the record-number mask is built with
+  // the same primitive as the AEAD (AES-ECB vs ChaCha20), so `algo` is needed
+  // here, not just at deprotection time further down.
+  let algo = keys.algo || (keys.key.length === 32 ? 'aes-256-gcm' : 'aes-128-gcm');
+  let isChaCha = algo === 'chacha20-poly1305';
+
+  // Decrypt record number. Returns null for a ciphertext under 16 bytes, which
+  // RFC 9147 §4.2.3 requires us to reject as a deprotection failure.
+  let rn = maskRecordNumber(keys.snKey, encRn, ciphertext, algo);
+  if (rn === null) return null;
   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
@@ -956,7 +1053,9 @@ function decryptEncryptedDtls13(data, keys) {
   let seq = reconstructDtlsSeq(truncated, hdr.seqLen2 ? 16 : 8,
                                (keys.maxReadSeq === undefined ? -1 : keys.maxReadSeq));
 
-  // Rebuild AAD with plaintext RN
+  // Rebuild AAD with plaintext RN. AAD depends only on the wire bytes (the
+  // decrypted record number + length), NOT on the reconstructed full seq —
+  // so it's computed once and reused across seq candidates below.
   let hdrLen = 1 + rnLen + (hdr.hasLength ? 2 : 0);
   let aad = new Uint8Array(hdrLen);
   aad[0] = data[0];
@@ -966,39 +1065,80 @@ function decryptEncryptedDtls13(data, keys) {
     aad[1 + rnLen + 1] = ctLen & 0xFF;
   }
 
-  let nonce = getNonce(keys.iv, seq);
-  let algo = keys.algo || (keys.key.length === 32 ? 'aes-256-gcm' : 'aes-128-gcm');
-  let isChaCha = algo === 'chacha20-poly1305';
-
-  if (ciphertext.length < 16) return null;
   let ct = ciphertext.subarray(0, ciphertext.length - 16);
   let tag = ciphertext.subarray(ciphertext.length - 16);
 
-  try {
-    let decipher = crypto.createDecipheriv(algo, keys.key, nonce,
-      isChaCha ? { authTagLength: 16 } : undefined);
-    decipher.setAAD(aad, isChaCha ? { plaintextLength: ct.length } : undefined);
-    decipher.setAuthTag(tag);
-    let pt = decipher.update(ct);
-    decipher.final();
+  // The wire carries only the low bits of the record seq. reconstructDtlsSeq
+  // returns the most-likely full value, but under large gaps or reordering
+  // the true seq can be one window away in either direction. Only the NONCE
+  // depends on the full seq (AAD does not), so try the neighbouring
+  // candidates on AEAD failure before giving up — this is what lets
+  // DTLS-Replay-TLS13 / -LargeGaps / -NonMonotonic deprotect instead of
+  // failing as "bad record MAC". Candidates are deduped and non-negative.
+  let window = hdr.seqLen2 ? 65536 : 256;
+  let candidates = [seq];
+  if (seq - window >= 0) candidates.push(seq - window);
+  candidates.push(seq + window);
+
+  let pt = null, acceptedSeq = -1;
+  for (let ci = 0; ci < candidates.length; ci++) {
+    let cand = candidates[ci];
+    let nonce = getNonce(keys.iv, cand);
+    try {
+      let decipher = crypto.createDecipheriv(algo, keys.key, nonce,
+        isChaCha ? { authTagLength: 16 } : undefined);
+      decipher.setAAD(aad, isChaCha ? { plaintextLength: ct.length } : undefined);
+      decipher.setAuthTag(tag);
+      let out = decipher.update(ct);
+      decipher.final();
+      pt = out; acceptedSeq = cand;
+      break;
+    } catch (e) {
+      // try next candidate
+    }
+  }
+
+  if (pt === null) return null;
+  seq = acceptedSeq;
 
+  {
     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) {
+    // RFC 9147 §4.5.1 anti-replay: only AFTER the tag verifies do we consult
+    // and update the sliding window. Checking before deprotection would let a
+    // forged record number poison the window; checking after means only
+    // genuine records move it. The window lives on the per-epoch key object,
+    // next to maxReadSeq, because both are per-epoch receive state.
+    //   replayWindow: bitmask of the 64 seqs at or below maxReadSeq that have
+    //   been accepted. Bit 0 = maxReadSeq, bit k = maxReadSeq - k.
+    if (keys.maxReadSeq === undefined || keys.maxReadSeq < 0) {
+      // First accepted record in this epoch: seed the window with this seq as
+      // the high-water mark (bit 0 set), so an immediate replay of it is
+      // caught below rather than sailing through an unset window.
+      keys.maxReadSeq = seq;
+      keys.replayWindow = 1n;
+    } else if (seq > keys.maxReadSeq) {
+      // Advance: shift the window up by the gap, then set bit 0.
+      let shift = BigInt(seq - keys.maxReadSeq);
+      keys.replayWindow = shift >= 64n ? 1n : ((keys.replayWindow << shift) | 1n) & ((1n << 64n) - 1n);
       keys.maxReadSeq = seq;
+    } else {
+      let back = BigInt(keys.maxReadSeq - seq);
+      if (back >= 64n) return null;                // too old — outside window
+      let bit = 1n << back;
+      if (keys.replayWindow & bit) return null;     // already seen — replay
+      keys.replayWindow |= bit;
     }
 
     return {
-      epoch: hdr.epoch,
+      // The caller resolves the full epoch (resolveReadEpoch); hdr.epoch is
+      // only its low 2 bits and must never escape this function as an epoch.
+      epoch: (fullEpoch === undefined || fullEpoch === null) ? hdr.epoch : fullEpoch,
       seq: seq,
       type: inner.type,
       content: inner.content,
       total_length: off + ctLen,
     };
-  } catch (e) {
-    return null;
   }
 }
 
@@ -1021,22 +1161,48 @@ function parseDtlsDatagram(data, keysByEpoch) {
 
     if (isUnifiedHdr(first)) {
       let hdr = parseUnifiedHdr(first);
-      let keys = keysByEpoch ? keysByEpoch[hdr.epoch] : null;
+      // Header carries 2 epoch bits; map them back to a real epoch first.
+      let fullEpoch = resolveReadEpoch(hdr.epoch, keysByEpoch);
+      let keys = (fullEpoch === null) ? null : keysByEpoch[fullEpoch];
 
       if (!keys) {
-        // Can't decrypt — try to skip
+        // No keys for this epoch YET. Do not discard the record: a DTLS peer
+        // legitimately packs its whole flight into one datagram, so the very
+        // record that lets us derive these keys (the ServerHello) can sit
+        // ahead of records encrypted under them. Throwing the rest away meant
+        // the entire encrypted flight vanished and the handshake stalled until
+        // the peer retransmitted — or forever, if it does not.
+        //
+        // Keep the raw bytes and mark the record deferred; the caller retries
+        // it after processing each earlier record, once the keys exist. This
+        // generalises the CCS-only re-decrypt that DTLS 1.2 already had.
         let rnLen = hdr.seqLen2 ? 2 : 1;
         let skip = 1 + rnLen;
+        let total;
         if (hdr.hasLength && off + skip + 2 <= data.length) {
-          skip += 2 + readU16(data, off + skip);
+          total = skip + 2 + readU16(data, off + skip);
         } else {
-          skip = data.length - off;
+          total = data.length - off;
         }
-        off += skip;
+        if (total <= 0 || off + total > data.length) total = data.length - off;
+
+        records.push({
+          // Unresolvable epoch: keep the raw bits so the deferred retry can
+          // resolve again once keys for that generation are installed.
+          type: null,
+          epoch: hdr.epoch,
+          epochBits: hdr.epoch,
+          seq: null,
+          content: null,
+          encrypted: false,
+          deferred: true,
+          raw: data.subarray(off, off + total),
+        });
+        off += total;
         continue;
       }
 
-      let result = decryptEncryptedDtls13(data.subarray(off), keys);
+      let result = decryptEncryptedDtls13(data.subarray(off), keys, fullEpoch);
       if (result) {
         records.push({
           type: result.type,
@@ -1101,13 +1267,25 @@ function parseDtlsDatagram(data, keysByEpoch) {
 
 /** Build ACK payload. acks: [{ epoch, seq }, ...] */
 function buildDtlsAck(acks) {
-  let bodyLen = acks.length * 8;
+  // RFC 9147 §7:
+  //     struct { uint64 epoch; uint64 sequence_number; } RecordNumber;
+  //     struct { RecordNumber record_numbers<0..2^16-1>; } ACK;
+  // SIXTEEN bytes per entry. This wrote eight — a uint16 epoch and a uint48
+  // sequence number, which is the DTLS *1.2* record-number layout carried over
+  // by mistake. A conforming peer reads a record_numbers vector whose length is
+  // not a multiple of 16 and answers decode_error.
+  //
+  // It stayed hidden because the only ACKs this stack sent were during the
+  // handshake, where they are usually redundant, and because parseDtlsAck made
+  // the identical mistake — so two copies of this library agreed with each
+  // other and the peer's own well-formed ACKs were quietly misread.
+  let bodyLen = acks.length * 16;
   let out = new Uint8Array(2 + bodyLen);
   let off = 0;
   off = w_u16(out, off, bodyLen);
   for (let i = 0; i < acks.length; i++) {
-    off = w_u16(out, off, acks[i].epoch);
-    off = w_u48(out, off, acks[i].seq);
+    off = w_u64(out, off, acks[i].epoch);
+    off = w_u64(out, off, acks[i].seq);
   }
   return out;
 }
@@ -1118,9 +1296,10 @@ function parseDtlsAck(data) {
   let off = 2;
   let end = off + bodyLen;
   let acks = [];
-  while (off + 8 <= end) {
-    let epoch = readU16(data, off); off += 2;
-    let seq   = readU48(data, off); off += 6;
+  // 16 bytes per RecordNumber — see buildDtlsAck.
+  while (off + 16 <= end && off + 16 <= data.length) {
+    let epoch = readU64(data, off); off += 8;
+    let seq   = readU64(data, off); off += 8;
     acks.push({ epoch, seq });
   }
   return acks;
@@ -1133,6 +1312,9 @@ export {
   // AEAD
   getAeadAlgo,
 
+  // DTLS 1.3 epoch resolution
+  resolveReadEpoch,
+
   // TLS 1.3
   deriveKeys,
   getNonce,
@@ -1174,6 +1356,7 @@ export {
   // DTLS 1.3 unified header
   buildUnifiedHdr,
   parseUnifiedHdr,
+  reconstructDtlsSeq,
   maskRecordNumber,
 
   // DTLS 1.3 encrypted records
@@ -1186,4 +1369,4 @@ export {
   // DTLS 1.3 ACK
   buildDtlsAck,
   parseDtlsAck,
-};
+};

package/src/session/ecdh.js

@@ -90,7 +90,131 @@ function p384_get_shared_secret(localPrivateRaw, remotePublicRaw) {
   return new Uint8Array(ecdh.computeSecret(Buffer.from(remotePublicRaw)));
 }
 
+/**
+ * Named groups this module actually implements, in preference order.
+ *
+ * SINGLE SOURCE OF TRUTH: consumers (TLSSession defaults, TLSSocket options,
+ * DTLSSession) must derive their advertised supported_groups from this list
+ * rather than hardcoding their own. Previously three call sites carried three
+ * different hardcoded lists — DTLS advertised P-384 while TLS did not, even
+ * though the code below has supported it all along, so a peer offering only
+ * P-384 got "no curve supported by both" from a stack that could do P-384.
+ *
+ * Adding a curve should be a change to THIS file only.
+ */
+const NAMED_GROUP = {
+  X25519:    0x001d,
+  SECP256R1: 0x0017,
+  SECP384R1: 0x0018,
+};
+
+const SUPPORTED_GROUPS = [
+  NAMED_GROUP.X25519,     // preferred: fastest, no point validation pitfalls
+  NAMED_GROUP.SECP256R1,
+  NAMED_GROUP.SECP384R1,
+];
+
+function is_supported_group(group) {
+  return SUPPORTED_GROUPS.indexOf(group) >= 0;
+}
+
+/**
+ * Generate a keypair for any supported group.
+ * Returns { private_key, public_key } or null for an unsupported group.
+ */
+function generate_keypair(group) {
+  if (group === NAMED_GROUP.X25519) {
+    let priv = new Uint8Array(crypto.randomBytes(32));
+    return { private_key: priv, public_key: x25519_get_public_key(priv) };
+  }
+  if (group === NAMED_GROUP.SECP256R1) return p256_generate_keypair();
+  if (group === NAMED_GROUP.SECP384R1) return p384_generate_keypair();
+  return null;
+}
+
+/**
+ * Validate a peer's key_exchange value for `group` and normalize it to the
+ * form the primitives below expect.
+ *
+ * Point-format knowledge belongs HERE, next to the curve implementations —
+ * not in the handshake state machine, which only needs to know "valid or not"
+ * so it can decide whether to abort. Throws on anything malformed; the caller
+ * converts that into an illegal_parameter alert.
+ */
+function normalize_peer_public_key(group, pub) {
+  if (!pub || pub.length === 0) throw new Error('empty key_exchange');
+
+  if (group === NAMED_GROUP.X25519) {
+    if (pub.length !== 32) {
+      throw new Error('X25519 key_exchange must be 32 bytes, got ' + pub.length);
+    }
+    return pub;
+  }
+
+  let coordLen = (group === NAMED_GROUP.SECP256R1) ? 32
+               : (group === NAMED_GROUP.SECP384R1) ? 48 : 0;
+  if (coordLen === 0) throw new Error('unsupported group 0x' + (group >>> 0).toString(16));
+
+  // RFC 8446 §4.2.8.2: for the secp*r1 groups the key_exchange is an
+  // UNCOMPRESSED point — 0x04 || X || Y — and nothing else. The length is
+  // therefore exact.
+  //
+  // This used to also accept a bare X || Y (no 0x04) and re-prefix it, as a
+  // tolerance for TLS 1.2 peers that strip the prefix. That tolerance is a
+  // security hole, not a kindness: truncating a valid 65-byte P-256 point by
+  // one byte yields exactly 64 bytes, which the tolerance then reinterpreted
+  // as a DIFFERENT, prefix-less point and happily fed to the ECDH. The same
+  // arithmetic applies to P-384 (97 → 96). Malformed input must be rejected,
+  // not silently reinterpreted.
+  let expected = 1 + 2 * coordLen;
+
+  if (pub.length !== expected) {
+    // Name the two shapes we know we are refusing, so the failure is
+    // diagnosable rather than just "bad length".
+    if (pub.length === 2 * coordLen) {
+      throw new Error('key_exchange is missing the 0x04 uncompressed-point prefix (got ' +
+        pub.length + ' bytes, expected ' + expected + ')');
+    }
+    if (pub.length === 1 + coordLen && (pub[0] === 0x02 || pub[0] === 0x03)) {
+      throw new Error('compressed points are not permitted; key_exchange must be uncompressed (RFC 8446 §4.2.8.2)');
+    }
+    throw new Error('key_exchange must be a ' + expected + '-byte uncompressed point, got ' + pub.length);
+  }
+
+  if (pub[0] !== 0x04) {
+    throw new Error('key_exchange must start with the 0x04 uncompressed-point marker, got 0x' +
+      pub[0].toString(16));
+  }
+
+  // Whether the point actually lies on the curve is checked by the ECDH
+  // primitive below (node throws ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY), which
+  // happens before any secret is produced — so an off-curve point can never
+  // yield key material.
+  return pub;
+}
+
+/**
+ * Compute the ECDHE shared secret for any supported group.
+ * Validates the peer's public key first; throws on invalid input (including
+ * the RFC 7748 §6.1 all-zero X25519 result and node's own on-curve checks).
+ */
+function get_shared_secret(group, localPrivateRaw, remotePublicRaw) {
+  let pub = normalize_peer_public_key(group, remotePublicRaw);
+
+  if (group === NAMED_GROUP.X25519)    return x25519_get_shared_secret(localPrivateRaw, pub);
+  if (group === NAMED_GROUP.SECP256R1) return p256_get_shared_secret(localPrivateRaw, pub);
+  if (group === NAMED_GROUP.SECP384R1) return p384_get_shared_secret(localPrivateRaw, pub);
+
+  throw new Error('unsupported group 0x' + (group >>> 0).toString(16));
+}
+
 export {
+  NAMED_GROUP,
+  SUPPORTED_GROUPS,
+  is_supported_group,
+  generate_keypair,
+  normalize_peer_public_key,
+  get_shared_secret,
   x25519_get_public_key,
   x25519_get_shared_secret,
   p256_generate_keypair,

package/src/session/message.js

@@ -193,6 +193,10 @@ function parse_tls_message(data, negotiatedVersion) {
     out.type = 'certificate';
 
   } else if (message.type == wire.TLS_MESSAGE_TYPE.CERTIFICATE_VERIFY) {
+    // Decode scheme + signature so the session can actually VERIFY it.
+    // Previously only the raw body was handed up and no caller ever checked
+    // the signature — every peer signature was accepted unconditionally.
+    out = wire.parse_certificate_verify(message.body);
     out.type = 'certificate_verify';
     out.body = message.body;
 
@@ -204,7 +208,11 @@ function parse_tls_message(data, negotiatedVersion) {
     // TLS 1.2 and 1.3 have different wire formats for this message.
     // TLS 1.3: ticket_lifetime | ticket_age_add | ticket_nonce | ticket | extensions
     // TLS 1.2: ticket_lifetime_hint | ticket                     (RFC 5077)
-    if (negotiatedVersion === 0x0303) {
+    // 0xFEFD is DTLS 1.2, which uses the RFC 5077 wire format exactly as TLS
+    // 1.2 does. Testing only for 0x0303 sent a DTLS 1.2 ticket through the
+    // TLS 1.3 parser — the same class of bug as the Certificate encoding one:
+    // a version comparison that does not know DTLS exists.
+    if (negotiatedVersion === 0x0303 || negotiatedVersion === 0xFEFD) {
       out = wire.parse_new_session_ticket_tls12(message.body);
     } else {
       out = wire.parse_new_session_ticket(message.body);
@@ -218,6 +226,37 @@ function parse_tls_message(data, negotiatedVersion) {
   } else if (message.type == wire.TLS_MESSAGE_TYPE.CERTIFICATE_REQUEST) {
     out = wire.parse_certificate_request(message.body);
     out.type = 'certificate_request';
+
+    // Surface the requested signature algorithms as a plain field.
+    //
+    // In TLS 1.3 they arrive inside the extensions vector (RFC 8446 §4.3.2);
+    // in TLS 1.2 the decoder already returns them as `signature_algorithms`
+    // (RFC 5246 §7.4.4). The session asks for one name, so normalise here —
+    // exactly what normalize_hello does for the hello messages. Without this
+    // the 1.3 list was silently undefined and the client fell back to signing
+    // with its OWN preference, ignoring what the server actually asked for;
+    // a server that requested a specific algorithm then rejects the signature
+    // as an unsupported one.
+    if (out.signature_algorithms === undefined && Array.isArray(out.extensions)) {
+      for (let i = 0; i < out.extensions.length; i++) {
+        let e = out.extensions[i];
+        if (e && e.type === wire.TLS_EXT.SIGNATURE_ALGORITHMS && Array.isArray(e.value)) {
+          out.signature_algorithms = e.value;
+          break;
+        }
+      }
+    }
+
+  } else {
+    // No silent fall-through. Returning a typeless object here made every
+    // unrecognized handshake type vanish: the session's dispatch chain matched
+    // nothing and simply returned, so a peer could stream unknown (or
+    // version-illegal, e.g. HelloRequest in TLS 1.3) messages indefinitely with
+    // no alert and no state change. Name the message instead and let the
+    // session decide — which it can only do if it is told.
+    out.type = 'unknown_handshake';
+    out.handshake_type = message.type;
+    out.body = message.body;
   }
 
   return out;