lemon-tls 0.5.0 → 0.6.0

package/src/dtls_session.js

@@ -44,8 +44,11 @@ import {
 
 import {
   TLS_CIPHER_SUITES,
+  default_cipher_suites,
   hkdf_expand_label,
   derive_sn_key,
+  LABEL_PREFIX_TLS13,
+  LABEL_PREFIX_DTLS13,
 } from './crypto.js';
 
 import {
@@ -59,9 +62,12 @@ import {
   parseDtlsDatagram,
   buildDtlsAck,
   parseDtlsAck,
+  decryptEncryptedDtls13,
 } from './record.js';
 
 import { timingSafeEqualU8 } from './utils.js';
+import { SUPPORTED_GROUPS as ECDH_SUPPORTED_GROUPS } from './session/ecdh.js';
+import { default_signature_schemes } from './session/signing.js';
 
 
 // ============================================================
@@ -107,6 +113,20 @@ function insertCookieIntoClientHello(ch1, cookie) {
   return ch2;
 }
 
+// Handshake diagnostics — off by default; enabled via LEMON_DEBUG=1 (or
+// WEBRTC_DEBUG=1 so one flag lights up the whole webrtc-server stack).
+// Interop failures in DTLS are notoriously silent (a record that fails
+// decryption or ordering simply vanishes); these logs make every inbound
+// record, ordering decision, and completion visible without a packet dump.
+var LEMON_DEBUG = typeof process !== 'undefined' && process.env &&
+  (process.env.LEMON_DEBUG === '1' || process.env.WEBRTC_DEBUG === '1');
+function _ldbg() {
+  if (!LEMON_DEBUG) return;
+  if (typeof console !== 'undefined' && console.log) {
+    console.log.apply(console, ['[lemon-dtls]'].concat([].slice.call(arguments)));
+  }
+}
+
 function DTLSSession(options) {
   if (!(this instanceof DTLSSession)) return new DTLSSession(options);
   options = options || {};
@@ -117,6 +137,17 @@ function DTLSSession(options) {
   // ---- Internal TLSSession ----
   let tls = new TLSSession({
     isServer: isServer,
+    // RFC 9147 §5.3: the DTLS ClientHello's legacy_session_id "MUST be
+    // set to a zero-length vector" — the 32-byte compatibility sid is a
+    // TLS-over-TCP middlebox trick (RFC 8446 §4.1.2) that DTLS excludes
+    // (8446 appendix D.4: no compatibility mode over DTLS). The TLS
+    // engine generates the compat sid when none is supplied, so pin it
+    // empty for DTLS, both 1.2 and 1.3 profiles. (Also sidesteps a
+    // deployed-parser landmine: webrtc-dtls ≤0.7 reads the sid LENGTH
+    // byte and never the body, so any non-empty sid shears its whole
+    // ClientHello parse.)
+    sessionId: new Uint8Array(0),
+    srtpProfiles: options.srtpProfiles,
     servername: options.servername,
     SNICallback: options.SNICallback,
     rejectUnauthorized: options.rejectUnauthorized,
@@ -170,8 +201,32 @@ function DTLSSession(options) {
     // 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) }
+    // Flight tracking for retransmission.
+    //
+    // Stores PRE-ENCRYPTION descriptors — { epoch, contentType, payload } —
+    // never built records. Rebuilding at retransmit time (resendFlight) gives
+    // every retransmitted record a FRESH record sequence number, which is not
+    // an optimization but a hard requirement on two independent grounds:
+    //   1. DTLS 1.3 (RFC 9147 §4.2.1): the AEAD nonce is derived from the
+    //      record seq. Re-emitting a stored ciphertext repeats (key, nonce) —
+    //      catastrophic for GCM (key-stream reuse reveals plaintext XOR and
+    //      enables tag forgery). The old code stored fully-built records and
+    //      replayed the exact bytes.
+    //   2. Receivers reconstruct the full seq from its truncated wire form
+    //      relative to the highest seq seen (and BoGo outright requires
+    //      monotonic seqs from the shim) — a replayed old seq reconstructs to
+    //      a wrong full value and fails deprotection as "bad record MAC".
+    currentFlight: [],     // array of { epoch, contentType, payload: Uint8Array }
+    // RFC 6347 §4.2.4 flight discipline: a NEW flight begins with the first
+    // record we send after having accepted new handshake data from the peer.
+    // Set when inbound processing advances state; consumed (and reset) by
+    // the outgoing path, which then starts a fresh currentFlight. Without
+    // this boundary, flights ACCUMULATED: after the HVR exchange the client's
+    // flight 5 (CKE/CCS/Finished) was appended onto the CH2 still sitting in
+    // currentFlight, so a flight-5 retransmission replayed the ClientHello
+    // too — which a connected werift server answers with renegotiation(),
+    // destroying the session instead of recovering it.
+    newFlightPending: false,
     retransmitTimer: null,
     retransmitCount: 0,
     retransmitTimeout: 1000,
@@ -219,24 +274,17 @@ function DTLSSession(options) {
   // Server defaults — TLSSession client auto-populates these, but server expects them set externally
   if (isServer) {
     if (!tlsSetup.local_supported_cipher_suites) {
-      let ciphers = [];
-      if (versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0) {
-        ciphers.push(0x1301, 0x1302, 0x1303); // TLS 1.3 AEAD ciphers
-      }
-      if (versions.indexOf(DTLS_VERSION.DTLS1_2) >= 0) {
-        ciphers.push(0xC02F, 0xC030, 0xC02B, 0xC02C); // TLS 1.2 ECDHE ciphers
-      }
-      tlsSetup.local_supported_cipher_suites = ciphers;
+      // crypto.js owns the default suite list (see default_cipher_suites).
+      tlsSetup.local_supported_cipher_suites = default_cipher_suites(
+        versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0,
+        versions.indexOf(DTLS_VERSION.DTLS1_2) >= 0
+      );
     }
     if (!tlsSetup.local_supported_groups) {
-      tlsSetup.local_supported_groups = [0x001d, 0x0017, 0x0018];
+      tlsSetup.local_supported_groups = ECDH_SUPPORTED_GROUPS.slice(); // whatever ecdh.js implements
     }
-    tlsSetup.local_supported_signature_algorithms = [
-      0x0804, 0x0805, 0x0806,  // RSA-PSS
-      0x0403, 0x0503, 0x0603,  // ECDSA
-      0x0807, 0x0808,          // EdDSA
-      0x0401, 0x0501, 0x0601,  // PKCS#1
-    ];
+    // signing.js owns the scheme list; DTLS spans 1.2+1.3 so include PKCS#1.
+    tlsSetup.local_supported_signature_algorithms = default_signature_schemes();
   }
 
   // Server cert/key
@@ -274,10 +322,18 @@ function DTLSSession(options) {
     }
     transcriptMsgSeqs.push(msgSeq);
 
-    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_2) {
-      return build_dtls_handshake(data, msgSeq);
-    }
-    return data; // TLS format for DTLS 1.3 or unknown version
+    // RFC 9147 §5.5: the DTLS 1.3 transcript is made of *TLS-style* Handshake
+    // messages — message_seq, fragment_offset and fragment_length are REMOVED.
+    // DTLS 1.2 is the opposite: RFC 6347 §4.2.6 keeps the 12-byte DTLS header
+    // in the transcript. Getting this backwards breaks the Finished MAC only,
+    // long after every message parsed cleanly — which is why it presents as a
+    // late, unrelated-looking failure.
+    let entry = (ctx.selectedVersion === DTLS_VERSION.DTLS1_2)
+      ? build_dtls_handshake(data, msgSeq)
+      : data; // TLS format for DTLS 1.3 or not-yet-negotiated
+
+
+    return entry;
   };
 
   /**
@@ -298,31 +354,70 @@ function DTLSSession(options) {
   //  Key derivation
   // ============================================================
 
+  /**
+   * RFC 9147 §5.9: DTLS 1.3 derives with the "dtls13" label prefix (no trailing
+   * space), NOT TLS 1.3's "tls13 ". Using the TLS prefix yields a handshake in
+   * which every message parses and the transcripts match on both sides, and
+   * only the keys differ — the peer reports "bad record MAC" and nothing else.
+   * DTLS 1.2 does not use HKDF-Expand-Label at all (it uses the 1.2 PRF), so
+   * the branch only has to distinguish 1.3.
+   */
+  function dtlsLabelPrefix() {
+    return ctx.selectedVersion === DTLS_VERSION.DTLS1_3
+      ? LABEL_PREFIX_DTLS13
+      : LABEL_PREFIX_TLS13;
+  }
+
   function deriveEpochKeys(secret) {
     let cs = TLS_CIPHER_SUITES[ctx.cipherSuite];
     let empty = new Uint8Array(0);
-    let key = hkdf_expand_label(cs.hash, secret, 'key', empty, cs.keylen);
-    let iv = hkdf_expand_label(cs.hash, secret, 'iv', empty, 12);
+    let lp = dtlsLabelPrefix();
+    let key = hkdf_expand_label(cs.hash, secret, 'key', empty, cs.keylen, lp);
+    let iv = hkdf_expand_label(cs.hash, secret, 'iv', empty, 12, lp);
 
     let result = { key, iv };
 
     // DTLS 1.3: derive sn_key for record number encryption
     if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
-      result.snKey = derive_sn_key(cs.hash, secret, ctx.cipherSuite);
+      result.snKey = derive_sn_key(cs.hash, secret, ctx.cipherSuite, dtlsLabelPrefix());
       result.algo = getAeadAlgo(ctx.cipherSuite);
     }
 
     return result;
   }
 
+  /**
+   * The DTLS epoch a given key generation belongs to.
+   *
+   * DTLS 1.3 (RFC 9147 §6.1) numbers epochs 0=plaintext, 1=early data,
+   * 2=handshake, 3=application. DTLS 1.2 uses a single encrypted epoch 1.
+   * Which numbering applies depends on the negotiated version, so this must
+   * resolve the version FIRST and never assume a previous sync happened.
+   *
+   * The two callers used to differ: the handshake-secrets handler synced the
+   * version from the TLS session, the application-secrets handler did not sync
+   * at all. That asymmetry is only harmless while the version happens to be
+   * committed by the time each event fires. When it is not — the TLS engine
+   * commits negotiated values at the END of a reactive pass, and these events
+   * are emitted DURING one — the keys are filed under epoch 1 while records are
+   * later built for epoch 2/3. buildRecord then finds no keys, returns null,
+   * and the record is dropped silently: the peer sees nothing at all and times
+   * out. One helper, so both generations decide the same way.
+   */
+  function dtlsEpochForSecrets(isApplication) {
+    if (ctx.selectedVersion === null && tls.context.selected_version) {
+      ctx.selectedVersion = tls.context.selected_version;
+      if (ctx.selectedVersion === DTLS_VERSION.DTLS1_2) fixTranscriptForDtls12();
+    }
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) return isApplication ? 3 : 2;
+    return 1;
+  }
+
   tls.on('handshakeSecrets', function(localSecret, remoteSecret) {
-    // Ensure version is detected before key derivation
-    if (ctx.selectedVersion === null) ctx.selectedVersion = tls.context.selected_version;
+    let dtlsEpoch = dtlsEpochForSecrets(false);
     ctx.cipherSuite = tls.getCipher();
     ctx.hashName = TLS_CIPHER_SUITES[ctx.cipherSuite].hash;
 
-    let dtlsEpoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 2 : 1;
-
     ctx.keys[dtlsEpoch] = {
       write: deriveEpochKeys(localSecret),
       read: deriveEpochKeys(remoteSecret),
@@ -331,7 +426,7 @@ function DTLSSession(options) {
   });
 
   tls.on('appSecrets', function(localSecret, remoteSecret) {
-    let dtlsEpoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 3 : 1;
+    let dtlsEpoch = dtlsEpochForSecrets(true);
 
     ctx.keys[dtlsEpoch] = {
       write: deriveEpochKeys(localSecret),
@@ -389,6 +484,14 @@ function DTLSSession(options) {
       }
     }
 
+    // Flight boundary: first outgoing record after accepting peer data
+    // starts a fresh flight (clears the previous flight's records and
+    // resets the retransmit budget — RFC 6347 §4.2.4).
+    if (ctx.newFlightPending) {
+      ctx.newFlightPending = false;
+      startNewFlight();
+    }
+
     // DTLS 1.2: send CCS before first encrypted message (Finished)
     if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 && tlsEpoch === 1 && !ctx.localCcsSent) {
       sendCCS();
@@ -403,11 +506,39 @@ function DTLSSession(options) {
     // Build DTLS records and emit
     for (let i = 0; i < frags.length; i++) {
       let record = buildRecord(dtlsEpoch, CT.HANDSHAKE, frags[i]);
-      ctx.currentFlight.push(record);
-      ev.emit('packet', record);
+      // The flight captures the fragment, not the record — see currentFlight.
+      ctx.currentFlight.push({ epoch: dtlsEpoch, contentType: CT.HANDSHAKE, payload: frags[i] });
+      if (record) {
+        ev.emit('packet', record);
+      } else {
+        // buildRecord refused to build (no keys for an encrypted epoch).
+        // Dropping the record here without a word is how a key-epoch mismatch
+        // turns into an unexplained peer timeout instead of a diagnosable
+        // failure: nothing reaches the wire and nothing is reported. Surface
+        // it — the handshake cannot proceed either way.
+        ev.emit('error', new Error(
+          'DTLS: could not build outgoing handshake record for epoch ' + dtlsEpoch +
+          ' — no keys installed for that epoch'));
+        return;
+      }
     }
 
-    // Start retransmit timer after sending flight messages
+    // Start retransmit timer after sending flight messages.
+    //
+    // BUGFIX (one-shot initial ClientHello): ctx.state only left 'idle'
+    // inside feedDatagram — i.e. on the first INBOUND datagram. A
+    // client's first flight is sent before anything has been received,
+    // so the 'handshaking'-only guard below never armed the retransmit
+    // timer for flight 1. A lost or early-dropped ClientHello — e.g. one
+    // arriving while the peer's ICE layer still discards non-STUN
+    // traffic, a routine race right after nomination — was therefore
+    // never retransmitted, and the handshake hung silently forever
+    // (surfacing as connectionState stuck at 'connecting'). RFC 6347
+    // §4.2.4's flight state machine has no unguarded flights: every
+    // flight except the handshake-final one must sit under a retransmit
+    // timer. Sending a handshake flight IS handshaking — reflect that in
+    // the state before consulting it.
+    if (ctx.state === 'idle') ctx.state = 'handshaking';
     if (ctx.state === 'handshaking') {
       startRetransmitTimer();
     }
@@ -419,8 +550,21 @@ function DTLSSession(options) {
   function buildRecord(epoch, contentType, payload) {
     let epochKeys = ctx.keys[epoch];
 
+
     if (!epochKeys) {
-      // No keys → plaintext record
+      // DTLS 1.3 epochs 2 (handshake) and 3 (application) are ALWAYS
+      // encrypted — they carry the unified header (first byte 0x2c–0x2f). If
+      // we reach here without keys for such an epoch, emitting a classic
+      // 13-byte plaintext header (first byte = content type, e.g. 0x16/0x1a)
+      // would make the peer reject the record as "bad type byte" (RFC 9147
+      // §4). That only happens on a caller ordering bug (record built before
+      // its epoch's keys were installed); surface it instead of putting a
+      // malformed record on the wire. Epoch 0 is legitimately plaintext.
+      if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3 && epoch >= 2) {
+        ev.emit('error', new Error('DTLS 1.3: attempted to build epoch ' + epoch + ' record before keys installed'));
+        return null;
+      }
+      // No keys → plaintext record (epoch 0, or DTLS 1.2 pre-CCS)
       return buildDtlsPlaintext(contentType, epoch, nextWriteSeq(epoch), payload);
     }
 
@@ -481,6 +625,11 @@ function DTLSSession(options) {
    */
   function sendAlertRecord(epoch, alertData) {
     let record = buildRecord(epoch, CT.ALERT, alertData);
+    // buildRecord returns null when it refuses to emit a malformed record
+    // (DTLS 1.3 epoch >= 2 with no keys installed). Emitting that null as a
+    // packet pushes `null` into the transport; drop it instead — we already
+    // surfaced the reason through 'error'.
+    if (!record) return;
     ev.emit('packet', record);
   }
 
@@ -490,7 +639,21 @@ function DTLSSession(options) {
   function sendCCS() {
     if (ctx.localCcsSent) return;
     ctx.localCcsSent = true;
+    // The server's final flight OPENS with CCS — honor the flight boundary
+    // here too, before this record is captured.
+    if (ctx.newFlightPending) {
+      ctx.newFlightPending = false;
+      startNewFlight();
+    }
     let record = buildDtlsPlaintext(CT.CHANGE_CIPHER_SPEC, 0, nextWriteSeq(0), new Uint8Array([1]));
+    // RFC 6347 §4.2.4: the CCS is part of the flight and MUST be included
+    // when the flight is retransmitted. Captured as a descriptor (epoch 0,
+    // plaintext), so resendFlight rebuilds it with a fresh seq like every
+    // other record. Previously it was emitted but never captured, so a
+    // retransmitted final flight arrived WITHOUT the cipher-spec change and
+    // the peer could never decrypt the accompanying Finished — an
+    // unrecoverable stall under single-datagram loss.
+    ctx.currentFlight.push({ epoch: 0, contentType: CT.CHANGE_CIPHER_SPEC, payload: new Uint8Array([1]) });
     ev.emit('packet', record);
   }
 
@@ -513,6 +676,17 @@ function DTLSSession(options) {
 
     let records = parseDtlsDatagram(data, keysByEpoch);
 
+    if (LEMON_DEBUG) {
+      var _summ = [];
+      for (var _ri = 0; _ri < records.length; _ri++) {
+        var _r = records[_ri];
+        _summ.push('type=' + _r.type + ' epoch=' + _r.epoch + ' seq=' + _r.seq +
+          (_r.epoch > 0 && !_r.encrypted ? ' UNDECRYPTED' : ''));
+      }
+      _ldbg('rx datagram len=' + data.length + ' state=' + ctx.state +
+        ' records: [' + _summ.join(' | ') + ']');
+    }
+
     // 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
@@ -520,6 +694,24 @@ function DTLSSession(options) {
     let ackable = [];
 
     for (let i = 0; i < records.length; i++) {
+      // A record we could not decrypt when the datagram was parsed. Keys may
+      // have arrived since — processing an earlier record in THIS datagram
+      // (the ServerHello) is exactly what installs them. Retry now, in order,
+      // so a peer that packs its whole flight into one datagram is handled
+      // without waiting for a retransmit.
+      if (records[i].deferred) {
+        let epochKeys = ctx.keys[records[i].epoch];
+        let readKeys = epochKeys ? epochKeys.read : null;
+        if (!readKeys) continue;                 // still unreadable — let the peer retransmit
+        let dec = null;
+        try { dec = decryptEncryptedDtls13(records[i].raw, readKeys); } catch (e) { dec = null; }
+        if (!dec) continue;
+        records[i] = {
+          type: dec.type, epoch: dec.epoch, seq: dec.seq,
+          content: dec.content, encrypted: true, deferred: false,
+        };
+      }
+
       if (records[i].type === CT.HANDSHAKE &&
           ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
         ackable.push({ epoch: records[i].epoch, seq: records[i].seq });
@@ -553,6 +745,18 @@ function DTLSSession(options) {
 
   function processRecord(record) {
     if (record.type === CT.HANDSHAKE) {
+      // An epoch>0 record that could not be decrypted (keys not yet
+      // installed, AEAD failure) must NOT be fed to the handshake
+      // parser: its content is ciphertext, and parsing it yields a
+      // garbage "message" with attacker-controllable type/length fields.
+      // Drop it — DTLS is loss-tolerant by design, and the peer's (or
+      // our own flight-elicited) retransmission delivers a fresh copy
+      // once it can be decrypted.
+      if (record.epoch > 0 && !record.encrypted) {
+        _ldbg('skip undecrypted epoch=' + record.epoch + ' seq=' + record.seq +
+          ' len=' + (record.content ? record.content.length : 0));
+        return;
+      }
       processHandshakeRecord(record.content, record.epoch, record.encrypted);
     } else if (record.type === CT.APPLICATION_DATA) {
       if (ctx.state === 'connected') {
@@ -593,6 +797,8 @@ function DTLSSession(options) {
   function processHandshakeRecord(data, epoch, encrypted) {
     // A handshake record may contain multiple handshake messages
     let off = 0;
+    let sawMessage = false;   // record contained ≥1 parseable handshake message
+    let anyNew = false;       // ≥1 message advanced our state (not a duplicate)
     while (off + 12 <= data.length) {
       let parsed = parse_dtls_handshake(data.subarray(off));
 
@@ -600,21 +806,65 @@ function DTLSSession(options) {
       let totalLen = parsed.length;
       let fragOffset = parsed.frag_offset;
       let fragLen = parsed.frag_length;
+      sawMessage = true;
+      _ldbg('hs msg: type=' + parsed.type + ' msgSeq=' + msgSeq +
+        ' len=' + totalLen + ' frag=' + fragOffset + '+' + fragLen +
+        ' nextReadMsgSeq=' + ctx.nextReadMsgSeq);
 
       // Is this a complete message or a fragment?
       if (fragOffset === 0 && fragLen === totalLen) {
         // Complete message — feed directly
-        deliverHandshakeMessage(parsed.type, parsed.body, msgSeq);
+        if (deliverHandshakeMessage(parsed.type, parsed.body, msgSeq)) anyNew = true;
       } else {
         // Fragment — reassemble
-        reassembleFragment(parsed);
+        if (reassembleFragment(parsed)) anyNew = true;
       }
 
       off += 12 + fragLen;
     }
 
-    // Received handshake data → cancel retransmit (implicit ACK)
-    cancelRetransmit();
+    // ── Implicit-ACK discipline (RFC 6347 §4.2.4) ──
+    // Receiving a message from the peer's NEXT flight is the implicit ACK
+    // of ours — only then may our retransmit timer be cancelled. The
+    // previous unconditional cancelRetransmit() here also fired on pure
+    // RETRANSMISSIONS of the peer's PREVIOUS flight, which mean the exact
+    // opposite: our reply was lost. Two concrete deadlocks that caused:
+    //   1. Our cookie-bearing CH2 is lost → server retransmits its HVR
+    //      (seq 0, discarded as a duplicate) → cancel killed the CH2
+    //      timer → CH2 never resent → handshake dead.
+    //   2. Our final flight (CKE/CCS/Finished) is lost → server
+    //      retransmits its flight (all seqs below nextReadMsgSeq,
+    //      discarded) → cancel killed the flight timer → dead.
+    // NOTE: the implicit-ACK cancel deliberately does NOT live here.
+    // Everything in this function runs AFTER deliverHandshakeMessage,
+    // and TLS produces our response flight synchronously inside the
+    // feed — so a cancel at this point lands on the freshly-armed timer
+    // of the flight we JUST sent, not on the acknowledged one. The
+    // cancel happens at the acceptance points inside
+    // deliverHandshakeMessage instead, before the feed.
+    if (anyNew) {
+      // handled at acceptance time
+    } else if (sawMessage && ctx.currentFlight.length > 0 &&
+               ctx.state !== 'connected' &&
+               ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 &&
+               // Damping: a peer retransmits its flight as SEVERAL
+               // datagrams; without a guard, EACH duplicate datagram
+               // elicited a full resend of our flight — a ×N
+               // amplification burst that itself increased loss
+               // pressure. One resend per 250ms answers the peer's
+               // whole retransmitted flight exactly once.
+               (Date.now() - (ctx._lastDupElicitedResend || 0)) >= 250) {
+      ctx._lastDupElicitedResend = Date.now();
+      // Pure duplicate of a previous peer flight while we still have an
+      // outstanding flight of our own: the peer is telling us it never
+      // got our reply. Resend it immediately (RFC 6347 §4.2.4 responder
+      // behavior) rather than waiting out our own backoff. The regular
+      // timer keeps running unchanged, so the retransmit budget still
+      // bounds the total effort; the resend rate is naturally bounded by
+      // the peer's own retransmission schedule. DTLS 1.3 is excluded —
+      // it uses explicit ACKs (RFC 9147 §7) instead of flight inference.
+      resendFlight();
+    }
   }
 
   /**
@@ -631,7 +881,7 @@ function DTLSSession(options) {
     let key = parsed.msg_seq;
 
     // Ignore fragments for messages we've already delivered.
-    if (key < ctx.nextReadMsgSeq) return;
+    if (key < ctx.nextReadMsgSeq) return false;
 
     // DoS guard: the 24-bit `length` is attacker-controlled on the first
     // fragment. Reject anything claiming more than our cap BEFORE allocating,
@@ -639,7 +889,7 @@ function DTLSSession(options) {
     if (parsed.length > ctx.maxHandshakeMessageSize) {
       ev.emit('error', new Error('DTLS handshake message exceeds maxHandshakeMessageSize (' +
         parsed.length + ' > ' + ctx.maxHandshakeMessageSize + ')'));
-      return;
+      return false;
     }
 
     let frag = ctx.fragments[key];
@@ -656,7 +906,15 @@ function DTLSSession(options) {
     let end = parsed.frag_offset + parsed.frag_length;
 
     // Bounds guard against a malformed fragment claiming to exceed totalLength.
-    if (end > frag.totalLength) return;
+    if (end > frag.totalLength) return false;
+
+    // Coverage before this fragment — used to decide whether it contributed
+    // anything new (a retransmitted fragment that only re-covers known bytes
+    // is a duplicate for implicit-ACK purposes).
+    let coveredBefore = 0;
+    for (let cr = 0; cr < frag.ranges.length; cr++) {
+      coveredBefore += frag.ranges[cr][1] - frag.ranges[cr][0];
+    }
 
     // Copy the fragment bytes in (overlaps simply overwrite with identical data).
     frag.buf.set(parsed.body.subarray(0, parsed.frag_length), start);
@@ -675,27 +933,44 @@ function DTLSSession(options) {
     }
     frag.ranges = merged;
 
+    let coveredAfter = 0;
+    for (let ca = 0; ca < merged.length; ca++) {
+      coveredAfter += merged[ca][1] - merged[ca][0];
+    }
+
+
     // 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);
+      return deliverHandshakeMessage(frag.type, frag.buf, key);
     }
+    return coveredAfter > coveredBefore;
   }
 
   /**
    * Deliver a complete handshake message to TLSSession.
    * Strips DTLS reconstruction → builds TLS format.
+   *
+   * @returns {boolean} true if the message advanced our handshake state
+   *   (delivered in-order, buffered out-of-order, or consumed as a valid
+   *   HVR / cookie-exchange step); false if it was a duplicate or was
+   *   dropped. processHandshakeRecord uses this for the implicit-ACK
+   *   decision — only genuinely new data may cancel our retransmit timer.
    */
   function deliverHandshakeMessage(type, body, msgSeq) {
     // Skip if we've already processed this msg_seq (duplicate / retransmit).
-    if (msgSeq < ctx.nextReadMsgSeq) return;
+    if (msgSeq < ctx.nextReadMsgSeq) return false;
 
     // Check for HelloVerifyRequest (DTLS 1.2 server→client, type=3)
     if (type === 3 && !isServer) {
       ctx.nextReadMsgSeq = msgSeq + 1;
+      // The HVR acknowledges CH1 (implicit ACK, RFC 6347 §4.2.4). No
+      // explicit cancel is needed: triggerClientHelloWithCookie arms the
+      // CH2 flight's own timer, and startRetransmitTimer clears any
+      // previous timer as its first step.
       let hvr = parse_hello_verify_request(body);
       triggerClientHelloWithCookie(hvr.cookie);
-      return;
+      return true;
     }
 
     // ---- Server-side HelloVerifyRequest cookie exchange (RFC 6347 §4.2.1) ----
@@ -707,27 +982,84 @@ function DTLSSession(options) {
     //
     // 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) {
-
+    if (type === 1 && isServer) {
       let ch = null;
       try { ch = parse_hello({ kind: 'client', body: body }); } catch (e) { ch = null; }
+
+      // Does this ClientHello offer DTLS 1.3?
+      //
+      // RULE: a decision derived from an incoming message is read from that
+      // message, never from state the message itself is about to establish.
+      // (Stated in full next to params_to_set in tls_session.js; this is the
+      // fourth bug it has caused.) Read it from the MESSAGE, never
+      // from ctx.selectedVersion — when the first ClientHello arrives nothing
+      // has been negotiated yet, so a state-based test reads null and fails
+      // OPEN. That matters because the two rules below are MUST-level and
+      // version-specific.
+      let offersDtls13 = false;
+      if (ch && Array.isArray(ch.supported_versions)) {
+        offersDtls13 = ch.supported_versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0;
+      }
+
+      // RFC 9147 §5.3: "A DTLS 1.3-only client MUST set the legacy_cookie field
+      // to zero length. If a DTLS 1.3 ClientHello is received with any other
+      // value in this field, the server MUST abort the handshake with an
+      // 'illegal_parameter' alert." DTLS 1.3 carries cookies in the `cookie`
+      // EXTENSION; the legacy body field is vestigial and must stay empty.
+      if (offersDtls13 && ch && ch.dtls_cookie && ch.dtls_cookie.length > 0) {
+        tls.sendAlert(2, 47); // fatal, illegal_parameter
+        ev.emit('error', new Error(
+          'DTLS 1.3 ClientHello carries a non-empty legacy_cookie (' +
+          ch.dtls_cookie.length + ' bytes) — RFC 9147 §5.3 requires zero length'));
+        return false;
+      }
+
+      // RFC 9147 §5.1: "DTLS 1.3-compliant implementations MUST NOT use the
+      // HelloVerifyRequest to execute a return-routability check." DTLS 1.3
+      // does return-routability with HelloRetryRequest + the cookie extension
+      // instead. The old guard tested ctx.selectedVersion, which is null here,
+      // so a DTLS 1.3 handshake could still be answered with an HVR.
+      if (options.useCookies === true && !offersDtls13) {
+
       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).
+        // Counts as progress: a retransmitted cookieless CH means the client
+        // never got our HVR — resending it here IS the correct response.
         sendHelloVerifyRequest();
-        return;
+        return true;
       }
 
       // 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;
+        return false;
+      }
+      // Cookie verified → accept this ClientHello as the handshake anchor.
+      //
+      // Strict RFC 6347 §4.2.2 (see the figure in the RFC): the cookie-
+      // bearing CH2 arrives with message_seq 1, and our ServerHello must
+      // be numbered 1 as well. The previous code assumed the retried CH
+      // "reuses msg_seq" 0 — that is only true for a pure retransmission
+      // of CH1 (HVR lost), not for the cookie-bearing CH2, so RFC-
+      // compliant clients (pion, OpenSSL, fixed lemon-tls) had their CH2
+      // buffered as "out of order" forever and the handshake deadlocked.
+      //
+      // Set the read cursor and the outgoing counter to 1; the in-order
+      // check below then accepts exactly a seq-1 CH2 and rejects anything
+      // else (including seq-0 CH2s from pre-fix lemon-tls clients — non-
+      // compliant numbering is intentionally not accommodated). The
+      // transcript stays consistent on both sides because
+      // feedHandshakeToTls records the incoming wire seq and outgoing
+      // messages record message_sent_seq at emission — which is exactly
+      // what the Finished MAC hashes (RFC 6347 §4.2.6).
+        ctx.nextReadMsgSeq = 1;
+        tls.context.message_sent_seq = 1;
+        // Fall through and process the ClientHello normally.
       }
-      // Cookie verified → fall through and process the ClientHello normally.
     }
 
     // ---- In-order delivery (RFC 6347 §4.2.4 / RFC 9147 §5.2) ----
@@ -739,21 +1071,56 @@ function DTLSSession(options) {
       // Out of order — hold it (ignore a duplicate already buffered).
       if (!(msgSeq in ctx.pendingMessages)) {
         ctx.pendingMessages[msgSeq] = { type: type, body: body };
+        return true;    // new information, even if not yet deliverable
       }
-      return;
+      return false;     // duplicate of an already-buffered message
     }
 
-    // msgSeq === nextReadMsgSeq → feed it and advance.
+    // msgSeq === nextReadMsgSeq → accept. Timer discipline, per the
+    // RFC 6347 §4.2.4 state machine, in two halves:
+    //
+    //  1. A message from the peer's next flight is the implicit ACK of
+    //     ours — but it must RE-ARM the timer, not cancel it. While we
+    //     are in WAITING (peer's flight only partially received — e.g.
+    //     one datagram of the server's SH..SHD flight lost), timer
+    //     expiry retransmits OUR last flight, which elicits a full
+    //     retransmission of the peer's flight (a cookie-valid duplicate
+    //     CH2 makes werift resend flight 4, a duplicate Finished makes
+    //     it resend flight 6). An earlier revision cancelled here: one
+    //     lost datagram inside the peer's flight then left BOTH sides
+    //     timer-less and deadlocked — ~50% handshake failure at just 5%
+    //     random loss.
+    //
+    //  2. The re-arm must happen BEFORE feeding TLS: the feed can
+    //     synchronously produce our entire next flight, whose fresh
+    //     timer must not be clobbered afterwards (the original code
+    //     cancelled at the end of processHandshakeRecord — after the
+    //     response — so no responder flight was EVER protected by
+    //     retransmission).
+    //
+    //     When the feed does respond, the flight boundary (newFlightPending
+    //     → startNewFlight) resets the retransmit budget and the outgoing
+    //     path arms the new flight's timer, superseding this re-arm.
+    startRetransmitTimer();
+    ctx.newFlightPending = true;
     feedHandshakeToTls(type, body, msgSeq);
     ctx.nextReadMsgSeq = msgSeq + 1;
 
-    // Drain consecutively-numbered buffered messages.
+    // Drain consecutively-numbered buffered messages. Same pre-feed
+    // ordering applies; for a timer armed by an earlier feed in this very
+    // drain, cancelling here would be wrong — but a mid-flight response
+    // does not occur in TLS flows (a flight is answered only after its
+    // final message), so each pre-feed cancel can only ever hit an
+    // already-acknowledged flight's timer (usually already null).
     while (ctx.nextReadMsgSeq in ctx.pendingMessages) {
       let next = ctx.pendingMessages[ctx.nextReadMsgSeq];
       delete ctx.pendingMessages[ctx.nextReadMsgSeq];
+      startRetransmitTimer();
+      ctx.newFlightPending = true;
       feedHandshakeToTls(next.type, next.body, ctx.nextReadMsgSeq);
       ctx.nextReadMsgSeq++;
     }
+    return true;
   }
 
   /**
@@ -806,12 +1173,41 @@ function DTLSSession(options) {
     // RFC 6347: "the client MUST use the same parameter values"
     let ch2 = insertCookieIntoClientHello(ctx.savedClientHello, cookie);
 
-    // Reset state
+    // Reset state for the post-HVR handshake restart.
+    //
+    // RFC 6347 §4.2.1: the handshake transcript restarts at CH2 — the
+    // cookieless CH1 and the HelloVerifyRequest are NOT included in the
+    // handshake hash. Resetting the transcript is therefore correct.
+    //
+    // RFC 6347 §4.2.2, however, is explicit (see the figure in the RFC)
+    // that message_seq does NOT restart:
+    //
+    //       ClientHello (seq=1)  ------>       ← CH2 carries seq 1
+    //       (with cookie)
+    //                            <------ ServerHello (seq=1)
+    //
+    // The previous code reset BOTH directions of the counter to 0: it
+    // sent CH2 with msg_seq=0 and reset nextReadMsgSeq to 0. Against a
+    // spec-compliant server (pion, werift, OpenSSL — all send an HVR and
+    // then number ServerHello=1), the entire server flight (seq 1..N)
+    // landed in pendingMessages waiting forever for a seq-0 message that
+    // never comes: the handshake stalled silently — no error, no alert.
+    // It only ever worked lemon-tls↔lemon-tls because our own server
+    // sends an HVR only when options.useCookies is set, so the broken
+    // path was never exercised same-stack.
+    //
+    // nextReadMsgSeq is deliberately NOT touched here: the HVR branch in
+    // deliverHandshakeMessage already advanced it to 1, which is exactly
+    // where the server's ServerHello will arrive.
     tls.context.transcript = [];
     tls.context.hello_sent = true;
     tls.context.dtls_cookie = cookie;
-    tls.context.message_sent_seq = 0;
-    ctx.nextReadMsgSeq = 0;
+    // CH2 is message_seq 1. Set message_sent_seq BEFORE the transcript
+    // push so transcriptHook / transcriptMsgSeqs record seq 1 for CH2 —
+    // the Finished MAC hashes the DTLS reconstruction data including
+    // message_seq (RFC 6347 §4.2.6), so a transcript recording seq 0 for
+    // a wire message sent with seq 1 would fail Finished verification.
+    tls.context.message_sent_seq = 1;
     ctx.currentFlight = [];
     ctx.fragments = {};          // discard any partial reassembly from CH1 flight
     ctx.pendingMessages = {};    // discard any out-of-order buffer from CH1 flight
@@ -824,13 +1220,13 @@ function DTLSSession(options) {
       tls.context.transcriptHook ? tls.context.transcriptHook(ch2) : ch2
     );
 
-    // Build DTLS message and send
-    let dtlsMsg = build_dtls_handshake(ch2, 0);
+    // Build DTLS message and send — msg_seq 1 per the RFC figure above.
+    let dtlsMsg = build_dtls_handshake(ch2, 1);
     let record = buildRecord(0, CT.HANDSHAKE, dtlsMsg);
-    ctx.currentFlight = [record];
-    ev.emit('packet', record);
+    ctx.currentFlight = [{ epoch: 0, contentType: CT.HANDSHAKE, payload: dtlsMsg }];
+    if (record) ev.emit('packet', record);
 
-    tls.context.message_sent_seq = 1;
+    tls.context.message_sent_seq = 2;
     startRetransmitTimer();
   }
 
@@ -839,6 +1235,21 @@ function DTLSSession(options) {
   //  Flight tracking + retransmission
   // ============================================================
 
+  /**
+   * Rebuild and re-emit the current flight with FRESH record sequence numbers.
+   * See currentFlight's comment for why re-encryption (not byte replay) is
+   * mandatory. Each descriptor goes back through buildRecord, which pulls the
+   * next write seq for its epoch — so a retransmitted DTLS 1.3 record gets a
+   * new nonce, and a monotonic seq the receiver can reconstruct.
+   */
+  function resendFlight() {
+    for (let i = 0; i < ctx.currentFlight.length; i++) {
+      let f = ctx.currentFlight[i];
+      let record = buildRecord(f.epoch, f.contentType, f.payload);
+      if (record) ev.emit('packet', record);
+    }
+  }
+
   function startRetransmitTimer() {
     cancelRetransmit();
     ctx.retransmitTimer = setTimeout(function() {
@@ -849,10 +1260,8 @@ function DTLSSession(options) {
         return;
       }
 
-      // Retransmit entire current flight
-      for (let i = 0; i < ctx.currentFlight.length; i++) {
-        ev.emit('packet', ctx.currentFlight[i]);
-      }
+      // Retransmit entire current flight with fresh record seqs.
+      resendFlight();
 
       ctx.retransmitCount++;
       ctx.retransmitTimeout = Math.min(ctx.retransmitTimeout * 2, 60000);
@@ -910,6 +1319,8 @@ function DTLSSession(options) {
   });
 
   tls.on('secureConnect', function() {
+    _ldbg('handshake complete — secureConnect (version=0x' +
+      ((ctx.selectedVersion || tls.context.selected_version || 0).toString(16)) + ')');
     ctx.state = 'connected';
     cancelRetransmit();
     startNewFlight();
@@ -948,7 +1359,21 @@ function DTLSSession(options) {
 
   function close() {
     if (ctx.state === 'closed') return;
-    let epoch = ctx.state === 'connected' ? (ctx.selectedVersion === DTLS_VERSION.DTLS1_3 ? 3 : 1) : 0;
+    // Choose the epoch by what the PEER can read, not by whether WE consider
+    // the handshake finished — the same rule the TLS branch uses for alerts.
+    //
+    // "not connected yet" does not mean "no keys": once handshake keys exist
+    // the peer has switched to reading protected records, and a plaintext
+    // close_notify arrives with a classic DTLSPlaintext header where the peer
+    // requires the RFC 9147 §4 unified header. It then reports a bad record
+    // type instead of a clean shutdown. Mirror the ACK path, which already
+    // picks the highest epoch we hold write keys for.
+    let epoch;
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
+      epoch = ctx.keys[3] ? 3 : (ctx.keys[2] ? 2 : 0);
+    } else {
+      epoch = ctx.keys[1] ? 1 : 0;
+    }
     sendAlertRecord(epoch, new Uint8Array([1, 0])); // warning, close_notify
     ctx.state = 'closed';
     cancelRetransmit();
@@ -1003,6 +1428,16 @@ function DTLSSession(options) {
       return tls.exportKeyingMaterial(length, label, context_value);
     },
 
+    /**
+     * The negotiated DTLS-SRTP protection profile (RFC 5764), or null.
+     * Surfaced here because DTLS-SRTP is the reason the exporter exists for
+     * this transport — a caller that can export keying material must also be
+     * able to learn which profile those keys are for.
+     */
+    getSelectedSrtpProfile: function() {
+      return tls.getSelectedSrtpProfile();
+    },
+
     /** Peer's hello extensions: [{ type, name, data, value }]. */
     getRemoteExtensions: function() { return tls.getRemoteExtensions(); },
 
@@ -1041,4 +1476,4 @@ function DTLSSession(options) {
   return this;
 }
 
-export default DTLSSession;
+export default DTLSSession;