lemon-tls 0.6.0 → 0.9.0

package/src/dtls_socket.js

@@ -44,12 +44,14 @@ function DTLSSocket(udpSocket, options) {
     cert: options.cert,
     key: options.key,
     rejectUnauthorized: options.rejectUnauthorized,
+    checkServerIdentity: options.checkServerIdentity,
     requestCert: options.requestCert,
     ca: options.ca,
     alpnProtocols: options.alpnProtocols,
     minVersion: options.minVersion,
     maxVersion: options.maxVersion,
     mtu: options.mtu,
+    groups: options.groups,
     ticketKeys: options.ticketKeys,
     useCookies: options.useCookies,
     srtpProfiles: options.srtpProfiles,
@@ -130,6 +132,33 @@ function DTLSSocket(udpSocket, options) {
   self.getALPN = function() { return session.getALPN(); };
   self.getPeerCertificate = function() { return session.getPeerCertificate(); };
 
+  /** TLS fingerprints, { hash, raw } or null (see TLSSession): JA4 and JA5
+   *  of the ClientHello, JA4S of the ServerHello — in either role. */
+  self.getJA4 = function(opts) { return session.getJA4(opts); };
+  self.getJA5 = function(opts) { return session.getJA5(opts); };
+  self.getJA4S = function(opts) { return session.getJA4S(opts); };
+
+  /** Set the key and certificate for this connection (Node parity). */
+  self.setKeyCert = function(ctxOrOpts) {
+    if (session.setKeyCert) session.setKeyCert(ctxOrOpts);
+  };
+
+  /** Finished verify_data — the tls-unique channel binding of RFC 5929.
+   *  DTLS-SRTP callers use this alongside exportKeyingMaterial(). */
+  self.getFinished = function() {
+    let v = session.getFinished ? session.getFinished() : null;
+    return v == null ? undefined : v;
+  };
+  self.getPeerFinished = function() {
+    let v = session.getPeerFinished ? session.getPeerFinished() : null;
+    return v == null ? undefined : v;
+  };
+
+  /** Whether this connection resumed an earlier session. */
+  self.isSessionReused = function() {
+    return session.isSessionReused ? session.isSessionReused() : false;
+  };
+
   /** 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. */
@@ -194,6 +223,7 @@ function createDTLSServer(options, connectionListener) {
           minVersion: options.minVersion,
           maxVersion: options.maxVersion,
           mtu: options.mtu,
+          groups: options.groups,
           ticketKeys: options.ticketKeys,
           useCookies: options.useCookies,
           srtpProfiles: options.srtpProfiles,
@@ -270,12 +300,14 @@ function connectDTLS(options, callback) {
     remotePort: port,
     servername: options.servername || host,
     rejectUnauthorized: options.rejectUnauthorized,
+    checkServerIdentity: options.checkServerIdentity,
     requestCert: options.requestCert,
     ca: options.ca,
     alpnProtocols: options.alpnProtocols,
     minVersion: options.minVersion,
     maxVersion: options.maxVersion,
     mtu: options.mtu,
+    groups: options.groups,
   });
 
   if (callback) socket.on('connect', callback);

package/src/node_options.js

@@ -0,0 +1,138 @@
+// ============================================================
+//  node:tls option strings → the codes lemon-tls works with
+// ============================================================
+//
+// node:tls takes `ciphers`, `ecdhCurve` and `sigalgs` as OpenSSL strings,
+// colon-separated; lemon-tls works with code points (allowedCipherSuites,
+// groups, signatureAlgorithms). compat.js promised Node's API and never read
+// the three — a server given `ciphers` or `ecdhCurve` ran with the defaults
+// and said nothing. These turn them into the lists, once, where an option is
+// taken (compat.js, and QUICO for both TCP and QUIC), and refuse what cannot
+// be honoured, as Node does ("no cipher match", "Failed to set ECDH curve").
+//
+// What is understood:
+//   ciphers    suite names — OpenSSL's for TLS 1.2 (ECDHE-RSA-AES128-GCM-SHA256)
+//              and the standard ones (TLS_AES_128_GCM_SHA256, or for 1.2
+//              TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256), in the order given;
+//              `!name` / `-name` take one out; DEFAULT, HIGH and ALL stand for
+//              every suite this library implements — it implements no weak
+//              ones. Other OpenSSL keywords (aNULL, MD5, …) select nothing
+//              here and are skipped: what remains must name something.
+//   ecdhCurve  'auto' (the default list) or names: X25519, P-256
+//              (prime256v1, secp256r1), P-384 (secp384r1), and post-quantum:
+//              X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024,
+//              MLKEM512, MLKEM768, MLKEM1024 (OpenSSL's names; case ignored).
+//   sigalgs    scheme names (ecdsa_secp256r1_sha256, rsa_pss_rsae_sha256,
+//              ed25519, …) or OpenSSL's SIG+HASH form (ECDSA+SHA256,
+//              RSA-PSS+SHA256, RSA+SHA256).
+
+import { TLS_CIPHER_SUITES, DEFAULT_CIPHER_SUITES_TLS13, DEFAULT_CIPHER_SUITES_TLS12 } from './crypto.js';
+import { SERVER_DEFAULT_GROUPS } from './session/ecdh.js';
+import { MLDSA_AVAILABLE } from './session/signing.js';
+
+function splitList(s) {
+  return String(s).split(/[:,\s]+/).filter(function (x) { return x !== ''; });
+}
+
+var cipherByName = null;
+function cipherTable() {
+  if (cipherByName) return cipherByName;
+  cipherByName = {};
+  for (var code in TLS_CIPHER_SUITES) {
+    var info = TLS_CIPHER_SUITES[code];
+    if (info.name) cipherByName[info.name.toUpperCase()] = Number(code);
+    if (info.standardName) cipherByName[info.standardName.toUpperCase()] = Number(code);
+  }
+  return cipherByName;
+}
+
+/** `ciphers` → [code, …] in the order given. Throws when nothing is left. */
+function parseCiphers(str) {
+  if (str === undefined || str === null) return null;
+  if (typeof str !== 'string') throw new TypeError('ciphers must be a string, got ' + typeof str);
+  var table = cipherTable(), all = DEFAULT_CIPHER_SUITES_TLS13.concat(DEFAULT_CIPHER_SUITES_TLS12);
+  var out = [], removed = [];
+  var tokens = splitList(str);
+  for (var i = 0; i < tokens.length; i++) {
+    var t = tokens[i], neg = t[0] === '!' || t[0] === '-';
+    if (neg || t[0] === '+') t = t.slice(1);
+    var u = t.toUpperCase(), codes;
+    if (u === 'DEFAULT' || u === 'HIGH' || u === 'ALL') codes = all;
+    else if (u in table) codes = [table[u]];
+    else continue;                                   // a keyword this library has nothing for
+    for (var j = 0; j < codes.length; j++) {
+      if (neg) { removed.push(codes[j]); var k = out.indexOf(codes[j]); if (k >= 0) out.splice(k, 1); }
+      else if (out.indexOf(codes[j]) < 0 && removed.indexOf(codes[j]) < 0) out.push(codes[j]);
+    }
+  }
+  if (out.length === 0) throw new Error('ciphers: no cipher match in "' + str + '"');
+  return out;
+}
+
+var GROUPS = {
+  'X25519': 0x001d,
+  'P-256': 0x0017, 'PRIME256V1': 0x0017, 'SECP256R1': 0x0017,
+  'P-384': 0x0018, 'SECP384R1': 0x0018,
+  'X25519MLKEM768': 0x11ec,
+  'SECP256R1MLKEM768': 0x11eb, 'SECP384R1MLKEM1024': 0x11ed,
+  'MLKEM512': 0x0200, 'MLKEM768': 0x0201, 'MLKEM1024': 0x0202,
+};
+
+/** `ecdhCurve` → [group, …]; 'auto' → null, the role's own default list
+ *  (a server's has the hybrid first, a client's does not offer it unasked).
+ *  Throws on a name it does not implement. */
+function parseEcdhCurve(str) {
+  if (str === undefined || str === null) return null;
+  if (typeof str !== 'string') throw new TypeError('ecdhCurve must be a string, got ' + typeof str);
+  if (str.trim().toLowerCase() === 'auto') return null;
+  var out = [], tokens = splitList(str);
+  for (var i = 0; i < tokens.length; i++) {
+    var g = GROUPS[tokens[i].toUpperCase()];
+    if (g === undefined) throw new Error('ecdhCurve: unsupported curve "' + tokens[i] + '"');
+    // The hybrid group only where node:crypto has ML-KEM (session/ecdh.js).
+    if (SERVER_DEFAULT_GROUPS.indexOf(g) < 0) throw new Error('ecdhCurve: "' + tokens[i] + '" is not available in this Node.js');
+    if (out.indexOf(g) < 0) out.push(g);
+  }
+  if (out.length === 0) throw new Error('ecdhCurve: no curve in "' + str + '"');
+  return out;
+}
+
+var SCHEMES = {
+  'RSA_PKCS1_SHA256': 0x0401, 'RSA_PKCS1_SHA384': 0x0501, 'RSA_PKCS1_SHA512': 0x0601,
+  'ECDSA_SECP256R1_SHA256': 0x0403, 'ECDSA_SECP384R1_SHA384': 0x0503, 'ECDSA_SECP521R1_SHA512': 0x0603,
+  'RSA_PSS_RSAE_SHA256': 0x0804, 'RSA_PSS_RSAE_SHA384': 0x0805, 'RSA_PSS_RSAE_SHA512': 0x0806,
+  'ED25519': 0x0807, 'ED448': 0x0808,
+  'RSA_PSS_PSS_SHA256': 0x0809, 'RSA_PSS_PSS_SHA384': 0x080a, 'RSA_PSS_PSS_SHA512': 0x080b,
+  // ML-DSA (FIPS 204), as OpenSSL names it.
+  'MLDSA44': 0x0904, 'MLDSA65': 0x0905, 'MLDSA87': 0x0906,
+  // OpenSSL's SIG+HASH spelling.
+  'ECDSA+SHA256': 0x0403, 'ECDSA+SHA384': 0x0503, 'ECDSA+SHA512': 0x0603,
+  'RSA-PSS+SHA256': 0x0804, 'RSA-PSS+SHA384': 0x0805, 'RSA-PSS+SHA512': 0x0806,
+  'RSA+SHA256': 0x0401, 'RSA+SHA384': 0x0501, 'RSA+SHA512': 0x0601,
+};
+
+/** `sigalgs` → [scheme, …]. Throws on a name it does not know. */
+function parseSigalgs(str) {
+  if (str === undefined || str === null) return null;
+  if (typeof str !== 'string') throw new TypeError('sigalgs must be a string, got ' + typeof str);
+  var out = [], tokens = splitList(str);
+  for (var i = 0; i < tokens.length; i++) {
+    var s = SCHEMES[tokens[i].toUpperCase()];
+    if (s === undefined) throw new Error('sigalgs: unsupported signature algorithm "' + tokens[i] + '"');
+    // ML-DSA only where node:crypto has it (session/signing.js).
+    if (s >= 0x0904 && s <= 0x0906 && !MLDSA_AVAILABLE) throw new Error('sigalgs: "' + tokens[i] + '" is not available in this Node.js');
+    if (out.indexOf(s) < 0) out.push(s);
+  }
+  if (out.length === 0) throw new Error('sigalgs: none in "' + str + '"');
+  return out;
+}
+
+/** 'TLSv1.2' / 'TLSv1.3' → 0x0303 / 0x0304, as node:tls names them. */
+function parseTlsVersion(v, name) {
+  if (v === undefined || v === null) return null;
+  if (v === 'TLSv1.3') return 0x0304;
+  if (v === 'TLSv1.2') return 0x0303;
+  throw new Error(name + ': "' + v + '" is not supported (TLSv1.2 or TLSv1.3)');
+}
+
+export { parseCiphers, parseEcdhCurve, parseSigalgs, parseTlsVersion };

package/src/record.js

@@ -16,6 +16,7 @@ import {
   w_u8,
   w_u16,
   w_u48,
+  w_u64,
 } from './wire.js';
 
 // ===================== AEAD algorithm resolution =====================
@@ -372,10 +373,52 @@ function buildAad12(seqNum, recordType, plaintextLen) {
 }
 
 /**
- * Encrypt a TLS 1.2 GCM record fragment. Returns explicit_nonce(8) || ciphertext || tag(16).
+ * TLS 1.2 ChaCha20-Poly1305 (RFC 7905), shared by the three TLS 1.2 record
+ * functions below. Told apart from AES-GCM the way the DTLS 1.2 functions do
+ * it: by the write IV the key block gave the suite — 12 bytes for ChaCha20,
+ * a 4-byte salt for GCM. No explicit nonce on the wire; the nonce is the IV
+ * XOR the sequence number; the AAD is the same as GCM's.
+ *
+ * The TLS 1.2 functions handled GCM only. A ChaCha20 suite was negotiated —
+ * it is in the default offer, and clients without AES hardware prefer it —
+ * and then every record failed: the peer's Finished did not decrypt
+ * (bad_record_mac), and ours could not have been read either.
+ */
+function chacha12Seal(pt, key, iv12, seqNum, recordType) {
+  const cipher = crypto.createCipheriv('chacha20-poly1305', key, getChachaNonce12(iv12, seqNum), { authTagLength: 16 });
+  cipher.setAAD(buildAad12(seqNum, recordType, pt.length), { plaintextLength: pt.length });
+  const ct = cipher.update(pt);
+  cipher.final();
+  return { ct: ct, tag: cipher.getAuthTag() };
+}
+
+function chacha12Open(fragment, key, iv12, seqNum, recordType) {
+  if (fragment.length < 16) throw new Error('TLS 1.2 ChaCha20 fragment too short');
+  const ct  = fragment.subarray(0, fragment.length - 16);
+  const tag = fragment.subarray(fragment.length - 16);
+  const decipher = crypto.createDecipheriv('chacha20-poly1305', key, getChachaNonce12(iv12, seqNum), { authTagLength: 16 });
+  decipher.setAAD(buildAad12(seqNum, recordType, ct.length), { plaintextLength: ct.length });
+  decipher.setAuthTag(tag);
+  const pt = decipher.update(ct);
+  decipher.final();
+  return pt;
+}
+
+/**
+ * Encrypt a TLS 1.2 AEAD record fragment.
+ * AES-GCM (4-byte salt): explicit_nonce(8) || ciphertext || tag(16).
+ * ChaCha20-Poly1305 (12-byte IV): ciphertext || tag(16).
  * Perf: computes seq-bytes once for both explicit nonce and AAD (was computed twice).
  */
 function encrypt12(pt, key, salt4, seqNum, recordType) {
+  if (salt4.length === 12) {
+    const sealed = chacha12Seal(pt, key, salt4, seqNum, recordType);
+    const out12 = new Uint8Array(sealed.ct.length + 16);
+    out12.set(sealed.ct, 0);
+    out12.set(sealed.tag, sealed.ct.length);
+    return out12;
+  }
+
   // Shared big-endian seq encoding (used as both explicit_nonce and AAD[0..8])
   const hi = (seqNum / 0x100000000) | 0;
   const lo = seqNum >>> 0;
@@ -436,6 +479,23 @@ function encrypt12(pt, key, salt4, seqNum, recordType) {
  */
 function encryptCompleteRecord12(pt, key, salt4, seqNum, recordType, version) {
   const ptLen = pt.length;
+
+  // ChaCha20-Poly1305: header || ciphertext || tag — no explicit IV.
+  if (salt4.length === 12) {
+    const sealed = chacha12Seal(pt, key, salt4, seqNum, recordType);
+    const cBodyLen = ptLen + 16;
+    const cVer = version || 0x0303;
+    const cRec = Buffer.allocUnsafe(5 + cBodyLen);
+    cRec[0] = recordType & 0xff;
+    cRec[1] = (cVer >>> 8) & 0xff;
+    cRec[2] = cVer & 0xff;
+    cRec[3] = (cBodyLen >>> 8) & 0xff;
+    cRec[4] = cBodyLen & 0xff;
+    sealed.ct.copy(cRec, 5);
+    sealed.tag.copy(cRec, 5 + ptLen);
+    return cRec;
+  }
+
   // Record body: 8 explicit_iv + ptLen ciphertext + 16 tag
   const bodyLen = 8 + ptLen + 16;
   const ver = version || 0x0303;
@@ -492,11 +552,15 @@ function encryptCompleteRecord12(pt, key, salt4, seqNum, recordType, version) {
 }
 
 /**
- * Decrypt a TLS 1.2 GCM record fragment. Input: explicit_nonce(8) || ciphertext || tag(16).
+ * Decrypt a TLS 1.2 AEAD record fragment.
+ * AES-GCM input: explicit_nonce(8) || ciphertext || tag(16).
+ * ChaCha20-Poly1305 input: ciphertext || tag(16).
  * Perf: subarray (zero-copy views) instead of slice (copies); returns Node Buffer
  * (which IS a Uint8Array subclass) instead of re-copying to a plain Uint8Array.
  */
 function decrypt12(fragment, key, salt4, seqNum, recordType) {
+  if (salt4.length === 12) return chacha12Open(fragment, key, salt4, seqNum, recordType);
+
   if (fragment.length < 24) throw new Error('TLS 1.2 fragment too short');
 
   // Zero-copy views over the input
@@ -589,6 +653,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;
@@ -726,7 +795,9 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
     decipher.setAuthTag(tag);
     let pt = decipher.update(ct);
     decipher.final();
-    return new Uint8Array(pt);
+    // A view, not a copy: pt is a fresh Buffer that owns its whole
+    // ArrayBuffer and nothing else holds it. Same Uint8Array type as before.
+    return new Uint8Array(pt.buffer, pt.byteOffset, pt.byteLength);
   }
 
   // AES-GCM: strip the 8-byte explicit nonce.
@@ -742,7 +813,8 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
   decipher.setAuthTag(tag);
   let pt = decipher.update(ct);
   decipher.final();
-  return new Uint8Array(pt);
+  // A view, not a copy — see the ChaCha branch above.
+  return new Uint8Array(pt.buffer, pt.byteOffset, pt.byteLength);
 }
 
 /** Build complete encrypted DTLS 1.2 record (header + encrypted payload). */
@@ -800,10 +872,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 +961,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 +1031,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 +1095,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
@@ -968,10 +1131,6 @@ function decryptEncryptedDtls13(data, keys) {
     aad[1 + rnLen + 1] = ctLen & 0xFF;
   }
 
-  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);
 
@@ -1009,7 +1168,8 @@ function decryptEncryptedDtls13(data, keys) {
   seq = acceptedSeq;
 
   {
-    let inner = parseInnerPlaintext(new Uint8Array(pt));
+    // A view, not a copy: pt is the decipher's fresh Buffer, owned by no one else.
+    let inner = parseInnerPlaintext(new Uint8Array(pt.buffer, pt.byteOffset, pt.byteLength));
 
     // 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
@@ -1038,7 +1198,9 @@ function decryptEncryptedDtls13(data, keys) {
     }
 
     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,
@@ -1066,7 +1228,9 @@ 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) {
         // No keys for this epoch YET. Do not discard the record: a DTLS peer
@@ -1090,8 +1254,11 @@ function parseDtlsDatagram(data, keysByEpoch) {
         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,
@@ -1102,7 +1269,7 @@ function parseDtlsDatagram(data, keysByEpoch) {
         continue;
       }
 
-      let result = decryptEncryptedDtls13(data.subarray(off), keys);
+      let result = decryptEncryptedDtls13(data.subarray(off), keys, fullEpoch);
       if (result) {
         records.push({
           type: result.type,
@@ -1167,13 +1334,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;
 }
@@ -1184,9 +1363,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;
@@ -1199,6 +1379,9 @@ export {
   // AEAD
   getAeadAlgo,
 
+  // DTLS 1.3 epoch resolution
+  resolveReadEpoch,
+
   // TLS 1.3
   deriveKeys,
   getNonce,
@@ -1253,4 +1436,4 @@ export {
   // DTLS 1.3 ACK
   buildDtlsAck,
   parseDtlsAck,
-};
+};