lemon-tls 0.10.0 → 0.11.0

package/src/dtls_session.js

@@ -35,16 +35,24 @@ import createSecureContext from './secure_context.js';
 import {
   DTLS_VERSION,
   build_dtls_handshake,
+  build_dtls_fragment,
   parse_dtls_handshake,
   build_message,
   build_hello_verify_request,
   parse_hello_verify_request,
   parse_hello,
+  peer_alert_error,
+  local_alert_error,
+  read_peer_alert,
+  MAX_WARNING_ALERTS,
+  MAX_RECORD_PLAINTEXT,
+  TLS_ALERT,
+  TLS_MESSAGE_TYPE,
+  parseError,
 } from './wire.js';
 
 import {
   TLS_CIPHER_SUITES,
-  default_cipher_suites,
   hkdf_expand_label,
   derive_sn_key,
   LABEL_PREFIX_TLS13,
@@ -56,7 +64,8 @@ import {
   getAeadAlgo,
   deriveKeys,
   deriveKeys12,
-  decryptDtls12,
+  openDtls12,
+  acceptRecordSeq,
   buildDtlsPlaintext,
   buildEncryptedDtls12,
   buildEncryptedDtls13,
@@ -66,9 +75,8 @@ import {
   decryptEncryptedDtls13,
 } from './record.js';
 
-import { timingSafeEqualU8 } from './utils.js';
-import { SUPPORTED_GROUPS as ECDH_SUPPORTED_GROUPS, SERVER_DEFAULT_GROUPS } from './session/ecdh.js';
-import { default_signature_schemes } from './session/signing.js';
+import { timingSafeEqualU8, concatUint8Arrays } from './utils.js';
+import { versionsInRange, localLists } from './node_options.js';
 
 
 // ============================================================
@@ -121,6 +129,37 @@ function insertCookieIntoClientHello(ch1, cookie) {
 // 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');
+// The two settable link parameters, checked where they are set (option or
+// setter): a wrong value is a programming error, thrown at once.
+// The connectionId option (RFC 9146, RFC 9147 §9): the CID this side asks
+// for. true — a server, SERVER_CID_LEN random bytes (createDTLSServer finds
+// its connections by them); a client, an empty one (it needs none: the server
+// does not move) —, or the CID itself. TLSSession negotiates whatever it is.
+const SERVER_CID_LEN = 8;
+function connectionIdOption(v, isServer) {
+  if (v === true) return isServer ? new Uint8Array(crypto.randomBytes(SERVER_CID_LEN)) : new Uint8Array(0);
+  return v;
+}
+
+function checkedMtu(v, dflt) {
+  if (v === undefined || v === null) {
+    if (dflt !== undefined) return dflt;
+    throw new TypeError('DTLS mtu: a number of bytes is required');
+  }
+  if (!Number.isInteger(v) || v < 128 || v > 65507) throw new RangeError('DTLS mtu must be an integer in [128, 65507], got ' + v);
+  return v;
+}
+// The least a timer from a round-trip estimate starts at (currentRto).
+const RTO_MIN_MS = 100;
+function checkedRetransmitTimeout(v, dflt) {
+  if (v === undefined || v === null) {
+    if (dflt !== undefined) return dflt;
+    throw new TypeError('DTLS initialRetransmitTimeout: a number of milliseconds is required');
+  }
+  if (!Number.isInteger(v) || v < 10 || v > 60000) throw new RangeError('DTLS initialRetransmitTimeout must be an integer in [10, 60000] ms, got ' + v);
+  return v;
+}
+
 function _ldbg() {
   if (!LEMON_DEBUG) return;
   if (typeof console !== 'undefined' && console.log) {
@@ -178,7 +217,12 @@ function DTLSSession(options) {
   let isServer = !!options.isServer;
 
   // ---- Internal TLSSession ----
-  let tls = new TLSSession({
+  // Every option goes on to the TLS session as the caller gave it — the
+  // TLS options (customExtensions, ALPNCallback, ticketData, signature and
+  // group choices, ...) mean the same over DTLS — and DTLS sets only these.
+  // A hand-picked list here left out whatever it did not name, as
+  // createDTLSServer's did (r96, A6).
+  let tls = new TLSSession(Object.assign({}, options, {
     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
@@ -190,37 +234,57 @@ function DTLSSession(options) {
     // 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,
-    checkServerIdentity: options.checkServerIdentity,
     // DTLS peers in WebRTC present self-signed certificates by design and are
     // authenticated by the SDP fingerprint, not by a CA chain. Falling back to
     // the platform trust store here would mark every such peer unauthorized.
     useDefaultCA: options.useDefaultCA === true,
-    ca: options.ca,
-    noTickets: options.noTickets,
-    requestCert: options.requestCert,
-    cert: options.cert,
-    key: options.key,
-    ticketKeys: options.ticketKeys,
-  });
+    // Resumption, as over TCP (TLSSocket): a 'session' Buffer from an
+    // earlier connection — a DTLS 1.3 PSK ticket, or a DTLS 1.2 RFC 5077
+    // ticket — and whether this side issues / asks for tickets (default
+    // true; noTickets: true is the older spelling of sessionTickets: false).
+    session: options.session || null,
+    sessionTickets: options.sessionTickets !== undefined ? options.sessionTickets !== false
+                                                         : options.noTickets !== true,
+    // No 0-RTT over DTLS here: early data has no DTLS record path.
+    earlyData: false,
+    connectionId: connectionIdOption(options.connectionId, isServer),
+  }));
 
   // ---- DTLS context ----
   let ctx = {
     state: 'idle',         // idle → handshaking → connected → closed
+    // Connection IDs (RFC 9146, RFC 9147 §9): { local, peer } once
+    // negotiated ('connectionId'), the peer's as NewConnectionId moves it;
+    // and the newest record number authenticated (noteNewest), the one
+    // a peer's new address may be taken from.
+    cid: null,
+    rxNewest: null,
+    consecutiveWarnings: 0,   // warning alerts with nothing else between them
+    // DTLS 1.3 ACK state (RFC 9147 §7.1), for the peer's flight in progress:
+    // the handshake records of it received so far, a timer for the ACK when
+    // the rest does not follow, and whether this datagram showed a gap.
+    lastFlight12: null,       // DTLS 1.2: our last flight, kept for the peer's retransmissions
+    dgAnyNew: false,          // this datagram: a handshake message not taken before
+    dgDuplicate: false,       // this datagram: a handshake message already taken
+    dgNewest: false,          // this datagram: a protected record newer than any before
+    pendingAcks: [],
+    ackTimer: null,
+    postAcks: [],             // post-handshake records received, to ACK together
+    postAckTimer: null,
+    ackDisruption: false,
+    flightMessagesQueued: 0,   // flight messages queued, ever (did this datagram answer with one?)
     isServer: isServer,
-    mtu: options.mtu || 1200,
+    mtu: checkedMtu(options.mtu, 1200),
 
     // Upper bound on a single reassembled handshake message. The DTLS handshake
     // header carries a 24-bit length (up to 16MB), which is attacker-controlled
     // on the very first fragment. Without a cap, a peer could send one fragment
     // claiming length 0xFFFFFF for several msg_seqs and force large allocations
-    // before anything is authenticated. 256KB comfortably fits a real
-    // certificate-chain flight while bounding the damage. Configurable via
-    // options.maxHandshakeMessageSize.
-    maxHandshakeMessageSize: options.maxHandshakeMessageSize || (256 * 1024),
+    // before anything is authenticated. TLS over TCP's limit
+    // (tls.handshakeMessageLimit(): 128 KB, or maxHandshakeSize) — it was a
+    // limit of DTLS's own, 256 KB. maxHandshakeMessageSize, its older
+    // option, is still taken (never past the same 128 KB).
+    maxHandshakeMessageSize: options.maxHandshakeMessageSize > 0 ? Math.min(options.maxHandshakeMessageSize, tls.handshakeMessageLimit()) : tls.handshakeMessageLimit(),
 
     // Version (determined after negotiation)
     selectedVersion: null,  // DTLS version (0xFEFC or 0xFEFD)
@@ -290,17 +354,41 @@ function DTLSSession(options) {
     // new write keys are installed immediately but stay dormant here until
     // the ACK arrives.
     pendingWriteEpoch: null,
-    keyUpdateFlight: null,     // { payload, epoch, timer, attempts, timeout }
+    postHandshake: [],         // DTLS 1.3 post-handshake messages awaiting their ACK
+    deferredKeyUpdate: null,   // DTLS 1.3: our KeyUpdate held back while one is unACKed (§8)
+    feeding: 0,                // inside feedDatagram: post-handshake messages wait for its end
+    seenPlainSeqs: [],         // the last epoch-0 record numbers received (duplicates dropped)
+    out: [],                   // what is to be sent, packed at the end of the pass (flushOut)
+    flightQueued: 0,           // messages of the current flight queued (haveFlight)
+    outScheduled: false,
+    heldPostHandshake: [],     // ...these (sendPostHandshake)
+    lastAckResend: 0,          // when an ACK that confirmed nothing new last caused a resend
     finalFlightPending: false, // DTLS 1.3 client: final flight not yet confirmed (see secureConnect)
 
     retransmitTimer: null,
     retransmitCount: 0,
-    retransmitTimeout: 1000,
+    retransmitTimeout: checkedRetransmitTimeout(options.initialRetransmitTimeout, 1000),
+    initialRetransmitTimeout: checkedRetransmitTimeout(options.initialRetransmitTimeout, 1000),   // where each flight's timer starts (RFC 9147 §5.8.2: 1 s)
+    // Given, the schedule is the caller's: no round-trip estimate moves it.
+    fixedRto: options.initialRetransmitTimeout !== undefined && options.initialRetransmitTimeout !== null,
+    lastSession: undefined,   // the last 'session' Buffer (getSession)
+    // Giving up (RFC 9147 §5.8.2 leaves it to us): after at least this many
+    // retransmissions AND this much time since the flight first went out.
+    // A count alone was 6 tries: about a minute from a 1 s timer, but 6 s from
+    // a 100 ms one (as WebRTC stacks start), too soon on a lossy path.
     maxRetransmits: 6,
+    giveUpAfter: 60000,
+    // Round-trip estimate (RFC 6298's, as RFC 9147 §5.8.2 invites: "the
+    // retransmit timer [...] SHOULD be adjusted from RTT samples"): from a
+    // flight sent once to the first new message of the answer (Karn: never
+    // from one retransmitted). Later flights' timers start from it.
+    srtt: null, rttvar: null,
+    flightBegan: null,         // when the current flight first went out (giving up)
+    rttStart: null,            // ...the same, until its answer is sampled (RTT)
+    flightResent: false,       // whether it has been resent
 
     // DTLS 1.2: CCS tracking
     localCcsSent: false,
-    remoteCcsSeen: false,
 
     // HelloVerifyRequest (DTLS 1.2 server)
     hvrCookie: null,       // cookie sent in HVR
@@ -313,58 +401,18 @@ function DTLSSession(options) {
   // ============================================================
 
   // Set DTLS versions and cookie (triggers DTLS format in build_hello)
-  let versions = [];
-  let minVer = options.minVersion || 'DTLSv1.2';
-  let maxVer = options.maxVersion || 'DTLSv1.3';
-  if (maxVer === 'DTLSv1.3' || maxVer === 'TLSv1.3') versions.push(DTLS_VERSION.DTLS1_3);
-  if (minVer === 'DTLSv1.2' || minVer === 'TLSv1.2' || maxVer === 'DTLSv1.2') versions.push(DTLS_VERSION.DTLS1_2);
-  if (versions.length === 0) versions = [DTLS_VERSION.DTLS1_3, DTLS_VERSION.DTLS1_2];
-
-  let tlsSetup = {
-    local_supported_versions: versions,
+  // node_options.js: the same reading as TLS over TCP. Inline compares took
+  // an unknown name silently.
+  let versions = versionsInRange(options.minVersion, options.maxVersion, true);
+
+  // The lists from the options (node_options.js localLists, as TLS over TCP
+  // builds them: the same names, cipherSuites and alpnProtocols as aliases);
+  // TLSSession fills what they leave out, by role (fill_default_lists). A
+  // DTLS server took no signatureAlgorithms nor prioritizeChaCha before, and
+  // a DTLS client offered every post-quantum group a server takes.
+  let tlsSetup = Object.assign(localLists(options, versions), {
     dtls_cookie: new Uint8Array(0),  // empty cookie — triggers DTLS format
-  };
-
-  // Pass through cipher/group/alpn preferences
-  if (options.cipherSuites) tlsSetup.local_supported_cipher_suites = options.cipherSuites;
-
-  // Client cipher defaults: TLSSession auto-populates both TLS 1.3+1.2 ciphers,
-  // but if we only support DTLS 1.2, we must not offer TLS 1.3 ciphers
-  // (the server might erroneously select one for a 1.2 connection).
-  if (!isServer && !options.cipherSuites && versions.indexOf(DTLS_VERSION.DTLS1_3) < 0) {
-    tlsSetup.local_supported_cipher_suites = [0xC02F, 0xC030, 0xC02B, 0xC02C, 0xCCA8];
-  }
-  if (options.groups) tlsSetup.local_supported_groups = options.groups;
-  if (options.alpnProtocols) tlsSetup.local_supported_alpns = options.alpnProtocols;
-
-  // Default key-exchange groups, BOTH roles. With DTLS 1.3 offered: the
-  // hybrid post-quantum group first (X25519MLKEM768, when node:crypto has
-  // ML-KEM — see ecdh.js), then the classical ones. In WebRTC either peer can
-  // end up the DTLS client, and harvest-now-decrypt-later applies to media
-  // too (Chrome rolls PQ DTLS out from 149). A client leading with the hybrid
-  // group sends a classical share beside it (tls_session), so a classical
-  // server costs nothing extra. DTLS 1.2 only: classical — a KEM does not fit
-  // its key exchange, and the server skips KEM groups there anyway.
-  if (!tlsSetup.local_supported_groups) {
-    // (ECDH_SUPPORTED_GROUPS leads with the hybrid too now; tls_session leaves
-    // a KEM group out of a hello that does not offer 1.3.)
-    tlsSetup.local_supported_groups = (versions.indexOf(DTLS_VERSION.DTLS1_3) >= 0
-      ? SERVER_DEFAULT_GROUPS : ECDH_SUPPORTED_GROUPS).slice();
-  }
-
-  // Server defaults — TLSSession client auto-populates these, but server expects them set externally
-  if (isServer) {
-    if (!tlsSetup.local_supported_cipher_suites) {
-      // 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
-      );
-    }
-    // (key-exchange groups: set above, for both roles)
-    // 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.
   //
@@ -373,13 +421,11 @@ function DTLSSession(options) {
   // pfx and ocsp, and picking out two fields silently dropped all of them —
   // an encrypted private key could never be decrypted here no matter what the
   // caller passed. Same defect the TLS paths carried.
-  if (options.cert && options.key) {
-    let sctx = createSecureContext(options);
-    tlsSetup.local_cert_chain = sctx.certificateChain;
-    tlsSetup.cert_private_key = sctx.privateKey;
-  }
-
+  // Through TLSSession's setKeyCert, as an SNICallback's context goes in:
+  // the key/certificate pairs — several (key: [...], cert: [...]), the one
+  // the client can verify chosen per handshake — not only the first.
   tls.set_context(tlsSetup);
+  if (options.cert && options.key) tls.setKeyCert(createSecureContext(options));
 
 
   // ============================================================
@@ -595,24 +641,22 @@ function DTLSSession(options) {
     if (ctx.writeEpoch === null || ctx.readEpoch === null) return;
 
     if (info.direction === 'send') {
-      // §8: only one KeyUpdate may be in flight. requestKeyUpdate() below
-      // refuses up front; reaching here with one pending means the TLS session
-      // rotated its secret anyway (e.g. an auto-response to the peer's
-      // update_requested while ours was still unacknowledged), which would
-      // strand an epoch. Say so rather than silently losing the connection.
+      // §8: only one KeyUpdate may be in flight. requestKeyUpdate() refuses
+      // up front; the TLS session's answer to the peer's update_requested
+      // is held back (deferredKeyUpdate). Anything else reaching here with
+      // one pending would strand an epoch: said, not lost in silence.
       if (ctx.pendingWriteEpoch !== null) {
+        // The secret of a KeyUpdate held back (deferredKeyUpdate): it takes
+        // effect when that one goes.
+        if (ctx.deferredKeyUpdate && ctx.deferredKeyUpdate.secret === null) {
+          ctx.deferredKeyUpdate.secret = info.secret;
+          return;
+        }
         ev.emit('error', new Error(
           'DTLS: a KeyUpdate is already awaiting acknowledgement (RFC 9147 §8)'));
         return;
       }
-      let next = ctx.writeEpoch + 1;
-      // Install the new write keys, but keep protecting with the old epoch
-      // until the peer ACKs (§8). ctx.keys[next] may already carry a .read
-      // half from the peer's own update — merge, never overwrite.
-      ctx.keys[next] = Object.assign({}, ctx.keys[next], { write: deriveEpochKeys(info.secret) });
-      ctx.writeSeq[next] = 0;
-      ctx.pendingWriteEpoch = next;
-
+      installWriteUpdate(info.secret);
     } else if (info.direction === 'receive') {
       let next = ctx.readEpoch + 1;
       ctx.keys[next] = Object.assign({}, ctx.keys[next], { read: deriveEpochKeys(info.secret) });
@@ -623,40 +667,259 @@ function DTLSSession(options) {
     }
   });
 
-  /** Arm the post-handshake retransmit for an unacknowledged KeyUpdate. */
-  function armKeyUpdateRetransmit(payload, epoch) {
-    cancelKeyUpdateRetransmit();
-    ctx.keyUpdateFlight = {
-      payload: payload, epoch: epoch,
-      attempts: 0, timeout: ctx.retransmitTimeout, timer: null,
+  // ── Datagrams ──
+  // Everything this side sends goes through one queue (ctx.out), and leaves
+  // it packed (flushOut): handshake messages of one epoch share a record —
+  // a message is cut where the space runs out, and the next goes on in the
+  // same record (RFC 6347 §4.2.3, RFC 9147 §5.5: several handshake messages
+  // or fragments to a record); records share a datagram, up to the MTU, each
+  // with its length (the DTLS 1.3 unified header's L bit is always set here:
+  // RFC 9147 §4.3, RFC 6347 §4.1.1). One record per message and one datagram
+  // per record left room unused (BoGo MTU-DTLS13: "previous packet had 212
+  // bytes available"); records alone packed into a datagram left room in the
+  // record (BoGo: "previous handshake record had 1107 bytes available, but
+  // shim did not fit another fragment in it"). Retransmissions are packed the
+  // same way: what is still unACKed, cut again to fill.
+  //   Items: { kind: 'msg', tlsMsg, msgSeq, epoch, list } — a whole handshake
+  //   message, fragmented here; each fragment becomes an entry of `list` (the
+  //   flight, a post-handshake message), what ACKs and retransmission act on;
+  //   { kind: 'entry', entry } — one of those, (re)sent; { kind: 'raw', epoch,
+  //   contentType, payload } — a record of its own (ACK, application data,
+  //   HelloVerifyRequest).
+  // A pass ends at the next microtask; at once before an alert (its own
+  // datagram: wolfSSL took a Finished and a close_notify packed together for
+  // a failed handshake) and when the session ends, so its last word is out
+  // before 'close'.
+  function queueOut(item) {
+    ctx.out.push(item);
+    if (!ctx.outScheduled) { ctx.outScheduled = true; queueMicrotask(function () { ctx.outScheduled = false; flushOut(); }); }
+  }
+  function queueMessage(tlsMsg, msgSeq, epoch, list, label) {
+    queueOut({ kind: 'msg', tlsMsg: tlsMsg, msgSeq: msgSeq, epoch: epoch, list: list, label: label });
+  }
+
+  // A handshake fragment entry cut in two: its first `n` body bytes stay, the
+  // rest becomes a new entry right after it in the same list.
+  function splitEntry(e, n) {
+    let p = e.payload, type = p[0], total = (p[1] << 16) | (p[2] << 8) | p[3];
+    let msgSeq = (p[4] << 8) | p[5], off = (p[6] << 16) | (p[7] << 8) | p[8];
+    let body = p.subarray(12);
+    let frag = function (o, b) { return build_dtls_fragment(type, total, msgSeq, o, b); };
+    let rest = { epoch: e.epoch, contentType: e.contentType, payload: frag(off + n, body.subarray(n)), list: e.list };
+    e.payload = frag(off, body.subarray(0, n));
+    if (e.list) { let i = e.list.indexOf(e); if (i >= 0) e.list.splice(i + 1, 0, rest); }
+    return rest;
+  }
+
+  // The most a record of ours carries: 2^14, or the peer's
+  // record_size_limit (RFC 8449) once negotiated — as TLSSocket's.
+  function flushOut() {
+    if (ctx.out.length === 0) return;
+    let queue = ctx.out;
+    ctx.out = [];
+    let parts = [], used = 0, rec = null, failed = false;
+    // Room left: in the datagram (the MTU), and in the record (2^14, or the
+    // peer's record_size_limit — RFC 8449).
+    let cap = tls.recordSendLimit();
+    let left = function () {
+      return Math.min(ctx.mtu - used - (rec ? recordOverhead(rec.epoch) + rec.len : 0), cap - (rec ? rec.len : 0));
+    };
+    let open = function (epoch, contentType, label) {
+      rec = { epoch: epoch, contentType: contentType, parts: [], entries: [], len: 0, label: label };
+    };
+    let closeRec = function () {
+      if (!rec) return;
+      let r = rec; rec = null;
+      let seq = (r.epoch in ctx.writeSeq) ? ctx.writeSeq[r.epoch] : 0;
+      let payload = r.parts.length === 1 ? r.parts[0] : concatUint8Arrays(r.parts);
+      let record = buildRecord(r.epoch, r.contentType, payload);
+      if (!record) {
+        // buildRecord refused (no keys for an encrypted epoch): said, not
+        // dropped in silence — the handshake cannot go on either way.
+        failed = true;
+        fail(new Error('DTLS: could not build outgoing record for epoch ' + r.epoch + ' — no keys installed for that epoch'), TLS_ALERT.INTERNAL_ERROR);
+        return;
+      }
+      let rn = recordNumber(r.epoch, seq);
+      for (let i = 0; i < r.entries.length; i++) (r.entries[i].sent || (r.entries[i].sent = [])).push(rn);
+      _ldbgTx(record, r.label || 'out');
+      parts.push(record); used += record.length;
+    };
+    let endDatagram = function () {
+      closeRec();
+      if (parts.length === 0) return;
+      let dg = parts.length === 1 ? parts[0] : concatUint8Arrays(parts);
+      parts = []; used = 0;
+      ev.emit('packet', dg);
+    };
+    // A record of `epoch` with at least `need` payload bytes: in this
+    // datagram if it fits, else the next.
+    let room = function (epoch, need) {
+      if (used > 0 && ctx.mtu - used < recordOverhead(epoch) + need) endDatagram();
     };
-    scheduleKeyUpdateRetransmit();
+    // Into the open handshake record of `epoch`, or a new one.
+    let intoHandshake = function (epoch, need, label) {
+      if (rec && (rec.epoch !== epoch || rec.contentType !== CT.HANDSHAKE || left() < need)) closeRec();
+      if (!rec) { room(epoch, need); open(epoch, CT.HANDSHAKE, label); }
+    };
+
+    for (let qi = 0; qi < queue.length && !failed; qi++) {
+      let item = queue[qi];
+      if (item.kind === 'msg') {
+        let body = item.tlsMsg.subarray(4), total = body.length, off = 0;
+        do {
+          intoHandshake(item.epoch, 12 + Math.min(total - off, 1), item.label);
+          let take = Math.max(0, Math.min(total - off, left() - 12));
+          let frag = build_dtls_handshake(item.tlsMsg, item.msgSeq, off, take);
+          let entry = { epoch: item.epoch, contentType: CT.HANDSHAKE, payload: frag, list: item.list };
+          item.list.push(entry);
+          rec.parts.push(frag); rec.entries.push(entry); rec.len += frag.length;
+          off += take;
+        } while (off < total && !failed);
+      } else if (item.kind === 'entry' && item.entry.contentType === CT.HANDSHAKE) {
+        let e = item.entry;
+        if (e.acked) continue;
+        intoHandshake(e.epoch, Math.min(e.payload.length, 13), item.label);
+        // Too long for what is left: cut to fill (a fragment's body only).
+        if (e.payload.length > left() && e.payload.length > 13 && left() >= 13) {
+          let rest = splitEntry(e, left() - 12);
+          queue.splice(qi + 1, 0, { kind: 'entry', entry: rest, label: item.label });
+        }
+        rec.parts.push(e.payload); rec.entries.push(e); rec.len += e.payload.length;
+      } else {
+        // A record of its own: a ChangeCipherSpec (an entry of the flight),
+        // an ACK, application data, a HelloVerifyRequest.
+        let e = item.kind === 'entry' ? item.entry : null;
+        if (e && e.acked) continue;
+        // A new entry (sendCCS): it joins its list here, in sending order.
+        if (e && item.join && e.list) e.list.push(e);
+        let epoch = e ? e.epoch : item.epoch, contentType = e ? e.contentType : item.contentType;
+        let payload = e ? e.payload : item.payload;
+        closeRec();
+        room(epoch, payload.length);
+        open(epoch, contentType, item.label);
+        rec.parts.push(payload); rec.len += payload.length;
+        if (e) rec.entries.push(e);
+        closeRec();
+      }
+    }
+    if (!failed) endDatagram();
+  }
+
+  // Our next write epoch's keys, from a KeyUpdate we sent: installed now, used
+  // from its ACK on (§8). ctx.keys[next] may already carry a .read half from
+  // the peer's own update — merge, never overwrite.
+  function installWriteUpdate(secret) {
+    let next = ctx.writeEpoch + 1;
+    ctx.keys[next] = Object.assign({}, ctx.keys[next], { write: deriveEpochKeys(secret) });
+    ctx.writeSeq[next] = 0;
+    ctx.pendingWriteEpoch = next;
+  }
+
+  // ── Post-handshake messages (RFC 9147 §5.8.4, §7.1) ──
+  // NewSessionTicket and KeyUpdate have no answering flight: each is
+  // resent on its own timer until the peer ACKs it — independently of the
+  // handshake flight and of each other. Only KeyUpdate was; a lost
+  // NewSessionTicket was simply lost (BoGo DTLS-Retransmit-*NewSessionTicket*).
+  // KeyUpdate's ACK also switches our write epoch (§8) — on the ACK that
+  // covers it, not on any ACK, as before.
+  // One made while a datagram is being taken in (feedDatagram) waits for its
+  // end — for the ACK that datagram may call for (§7.1). The server's
+  // NewSessionTickets come of the client's Finished: they went out ahead of
+  // its ACK, and a peer that waits for the ACK first (BoringSSL's runner)
+  // read the first ticket as renegotiation and the second as out of order
+  // (BoGo N1). A KeyUpdate answering the peer's follows its ACK the same way.
+  function sendPostHandshake(kind, tlsMsg, msgSeq, epoch) {
+    let item = { kind: kind, msg: { tlsMsg: tlsMsg, msgSeq: msgSeq, epoch: epoch }, entries: [],
+                 attempts: 0, timeout: currentRto(), timer: null, began: Date.now() };
+    ctx.postHandshake.push(item);
+    if (ctx.feeding > 0) { ctx.heldPostHandshake.push(item); return; }
+    transmitPostHandshake(item);
+  }
+  function transmitPostHandshake(item) {
+    queueMessage(item.msg.tlsMsg, item.msg.msgSeq, item.msg.epoch, item.entries, item.kind);
+    schedulePostHandshake(item);
+  }
+  function flushHeldPostHandshake() {
+    let held = ctx.heldPostHandshake;
+    ctx.heldPostHandshake = [];
+    for (let i = 0; i < held.length; i++) {
+      if (ctx.state === 'closed' || ctx.postHandshake.indexOf(held[i]) < 0) continue;
+      transmitPostHandshake(held[i]);
+    }
   }
 
-  function scheduleKeyUpdateRetransmit() {
-    let f = ctx.keyUpdateFlight;
-    if (!f) return;
-    f.timer = setTimeout(function () {
-      if (!ctx.keyUpdateFlight) return;
-      if (f.attempts >= ctx.maxRetransmits) {
-        ev.emit('error', new Error('DTLS: KeyUpdate was never acknowledged'));
-        cancelKeyUpdateRetransmit();
+  function schedulePostHandshake(item) {
+    item.timer = setTimeout(function () {
+      item.timer = null;
+      if (ctx.postHandshake.indexOf(item) < 0 || ctx.state === 'closed') return;
+      if (exhausted(item.attempts, item.began)) {
+        removePostHandshake(item);
+        // An unacknowledged KeyUpdate leaves the next epoch unusable; a
+        // ticket is an offer, and the connection is fine without it.
+        if (item.kind === 'key_update') ev.emit('error', new Error('DTLS: KeyUpdate was never acknowledged'));
         return;
       }
-      f.attempts++;
-      // Rebuild rather than replay: a retransmission is a NEW record and needs
-      // a fresh sequence number, or the peer's replay window rejects it.
-      let record = buildRecord(f.epoch, CT.HANDSHAKE, f.payload);
-      if (record) { _ldbgTx(record, 'keyupdate-rtx'); ev.emit('packet', record); }
-      f.timeout = Math.min(f.timeout * 2, 60000);
-      scheduleKeyUpdateRetransmit();
-    }, f.timeout);
-    if (f.timer && typeof f.timer.unref === 'function') f.timer.unref();
+      item.attempts++;
+      // Rebuilt, not replayed: each retransmission is a new record with a
+      // fresh sequence number, or the peer's replay window drops it.
+      transmitUnacked(item.entries, item.kind + '-rtx', false);
+      item.timeout = Math.min(item.timeout * 2, 60000);
+      schedulePostHandshake(item);
+    }, item.timeout);
+    if (item.timer && typeof item.timer.unref === 'function') item.timer.unref();
+  }
+
+  function removePostHandshake(item) {
+    if (item.timer) clearTimeout(item.timer);
+    let i = ctx.postHandshake.indexOf(item);
+    if (i >= 0) ctx.postHandshake.splice(i, 1);
+  }
+
+  // The session is over: every timer it runs stops with it.
+  function shutDown() {
+    flushOut();
+    ctx.state = 'closed';
+    cancelRetransmit();
+    cancelPostHandshake();
+    clearPendingAcks();
+  }
+
+  function cancelPostHandshake() {
+    for (let i = 0; i < ctx.postHandshake.length; i++) {
+      if (ctx.postHandshake[i].timer) clearTimeout(ctx.postHandshake[i].timer);
+    }
+    ctx.postHandshake = [];
+    ctx.heldPostHandshake = [];
+    ctx.deferredKeyUpdate = null;
   }
 
-  function cancelKeyUpdateRetransmit() {
-    if (ctx.keyUpdateFlight && ctx.keyUpdateFlight.timer) clearTimeout(ctx.keyUpdateFlight.timer);
-    ctx.keyUpdateFlight = null;
+  // The post-handshake messages an ACK covers (by record number): done.
+  // A second ACK of them finds nothing left, and changes nothing
+  // (BoGo ACKPostHandshakeTwice).
+  function ackPostHandshake(got) {
+    for (let i = ctx.postHandshake.length - 1; i >= 0; i--) {
+      let item = ctx.postHandshake[i];
+      if (item.entries.length === 0) continue;   // not out yet
+      markAcked(item.entries, got);
+      if (item.entries.some(function (e) { return !e.acked; })) continue;
+      removePostHandshake(item);
+      if (item.kind === 'key_update' && ctx.pendingWriteEpoch !== null) {
+        // §8: the new epoch becomes live on the ACK of the KeyUpdate.
+        ctx.writeEpoch = ctx.pendingWriteEpoch;
+        ctx.pendingWriteEpoch = null;
+        ev.emit('keyUpdate', { direction: 'send', epoch: ctx.writeEpoch });
+        if (ctx.state === 'closed') return;   // a listener closed it
+        // The KeyUpdate held back for this one (§8): now, under the epoch
+        // just made live — the one it replaces.
+        let held = ctx.deferredKeyUpdate;
+        if (held && held.secret !== null) {
+          ctx.deferredKeyUpdate = null;
+          sendPostHandshake('key_update', held.tlsMsg, held.msgSeq, ctx.writeEpoch);
+          installWriteUpdate(held.secret);
+        }
+      }
+    }
   }
 
 
@@ -689,28 +952,25 @@ function DTLSSession(options) {
       // epoch, which is 3 until a KeyUpdate moves it to 4, 5, ... Hardcoding 3
       // meant every post-handshake message stayed on the pre-rekey epoch.
       dtlsEpoch = (tlsEpoch === 1) ? 2
-                : (ctx.writeEpoch !== null ? ctx.writeEpoch : 3);
+                : appEpoch();
     } else {
       dtlsEpoch = 1;  // DTLS 1.2: epoch 1 for all encrypted
     }
 
     if (type === 'alert') {
-      sendAlertRecord(dtlsEpoch, data);
+      // TLSSession names the epoch the PEER reads at (sendAlert); this layer
+      // holds the keys. Its choice when we hold write keys for it, else the
+      // highest epoch we do (alertEpoch) — never a record for an epoch we
+      // have no keys for, which a DTLS 1.3 alert before any keys could
+      // become: a unified header the peer could not even parse ("bad type
+      // byte"; BoGo FragmentMessage*Mismatch).
+      let ae = (dtlsEpoch === 0 || (ctx.keys[dtlsEpoch] && ctx.keys[dtlsEpoch].write)) ? dtlsEpoch : alertEpoch();
+      sendAlertRecord(ae, data);
       return;
     }
 
-    // DTLS 1.2: derive keys before first encrypted message
-    if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 && tlsEpoch === 1 && !ctx.keys[1]) {
-      let ts = tls.getTrafficSecrets();
-      if (ts.masterSecret) {
-        let d12 = deriveKeys12(ts.masterSecret, ts.localRandom, ts.remoteRandom, tls.getCipher(), isServer);
-        ctx.keys[1] = {
-          write: { key: d12.writeKey, iv: d12.writeIv },
-          read:  { key: d12.readKey,  iv: d12.readIv },
-        };
-        ctx.writeSeq[1] = 0;
-      }
-    }
+    // DTLS 1.2: keys before the first encrypted message
+    if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 && tlsEpoch === 1) installKeys12();
 
     // Flight boundary: first outgoing record after accepting peer data
     // starts a fresh flight (clears the previous flight's records and
@@ -725,50 +985,32 @@ function DTLSSession(options) {
       sendCCS();
     }
 
-    // Convert TLS handshake message → DTLS handshake message (add reconstruction header)
-    let dtlsMsg = build_dtls_handshake(data, seq);
-
-    // Fragment if needed
-    let frags = fragmentMessage(dtlsMsg, data, seq);
-
-    // Build DTLS records and emit
+    // Out as a DTLS handshake message — fragmented as it is packed (flushOut).
     // RFC 9147 §5.8.4: post-handshake messages do NOT belong to the handshake
     // flight. Each category gets an independent state machine; folding a
     // KeyUpdate into currentFlight would make a handshake retransmission
     // replay it, and a KeyUpdate ACK cancel the handshake's timer.
-    let isPostHandshakeKU = (type === 'key_update' &&
-                             ctx.selectedVersion === DTLS_VERSION.DTLS1_3);
-    if (isPostHandshakeKU) {
-      for (let i = 0; i < frags.length; i++) {
-        let kuRecord = buildRecord(dtlsEpoch, CT.HANDSHAKE, frags[i]);
-        if (kuRecord) { _ldbgTx(kuRecord, 'keyupdate'); ev.emit('packet', kuRecord); }
+    // DTLS 1.3, after the handshake: KeyUpdate, NewSessionTicket — each on
+    // its own retransmission until ACKed (sendPostHandshake).
+    // (A TLS 1.3 NewSessionTicket is post-handshake whenever it goes — the
+    // server sends its first one just before it reports the handshake done.)
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3 &&
+        (type === 'new_session_ticket' || (type === 'key_update' && ctx.state === 'connected'))) {
+      // §8: one KeyUpdate at a time — "until the KeyUpdate message has been
+      // acknowledged" no other. Ours answering the peer's update_requested
+      // while our own is unACKed waits for that ACK (ackPostHandshake), then
+      // goes under the epoch it replaces. Sent at once, the next one's keys
+      // found an epoch still pending and the connection failed (BoringSSL,
+      // which delays its ACKs: every time).
+      if (type === 'key_update' && ctx.pendingWriteEpoch !== null) {
+        ctx.deferredKeyUpdate = { tlsMsg: data, msgSeq: seq, secret: null };
+        return;
       }
-      // KeyUpdate must be acknowledged (§8), so it is retransmitted on its own
-      // timer until an ACK arrives. Only the last fragment is tracked; a
-      // KeyUpdate body is 1 byte and never fragments in practice.
-      armKeyUpdateRetransmit(frags[frags.length - 1], dtlsEpoch);
+      sendPostHandshake(type, data, seq, dtlsEpoch);
       return;
     }
 
-    for (let i = 0; i < frags.length; i++) {
-      // The flight captures the fragment, not the record — see currentFlight.
-      let entry = { epoch: dtlsEpoch, contentType: CT.HANDSHAKE, payload: frags[i] };
-      let record = buildFlightRecord(entry);
-      ctx.currentFlight.push(entry);
-      if (record) {
-        _ldbgTx(record, 'L543'); 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;
-      }
-    }
+    queueFlightMessage(data, seq, dtlsEpoch);
 
     // Start retransmit timer after sending flight messages.
     //
@@ -817,67 +1059,151 @@ function DTLSSession(options) {
 
     if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
       // DTLS 1.3 encrypted (unified header)
-      return buildEncryptedDtls13(contentType, payload, nextWriteSeq(epoch), epoch, epochKeys.write);
+      return buildEncryptedDtls13(contentType, payload, nextWriteSeq(epoch), epoch, epochKeys.write, peerCid());
     } else {
       // DTLS 1.2 encrypted (classic header)
-      return buildEncryptedDtls12(contentType, epoch, nextWriteSeq(epoch), payload, epochKeys.write);
+      return buildEncryptedDtls12(contentType, epoch, nextWriteSeq(epoch), payload, epochKeys.write, peerCid());
     }
   }
 
+  // The CID the peer asked for, in every protected record we send (null:
+  // none). Ours, that the peer's carry: from the moment we ask for it — a
+  // record with it can come in the datagram that agrees to it (a resumed
+  // DTLS 1.2 server's Finished, behind its ServerHello) — and required once
+  // agreed to.
+  function peerCid() { return ctx.cid && ctx.cid.peer.length > 0 ? ctx.cid.peer : null; }
+  function localCid() { let c = tls.context.local_cid; return c && c.length > 0 ? c : null; }
+  function localCidRequired() { return !!(ctx.cid && ctx.cid.local.length > 0); }
+
   function nextWriteSeq(epoch) {
     if (!(epoch in ctx.writeSeq)) ctx.writeSeq[epoch] = 0;
     return ctx.writeSeq[epoch]++;
   }
 
   /**
-   * Fragment a DTLS handshake message if it exceeds MTU.
-   * Returns array of DTLS handshake message fragments (each with reconstruction header).
+   * The one way a handshake message of a flight goes out: queued, to be cut
+   * and packed (flushOut) into entries of the current flight — kept for
+   * retransmission — and counted as our answer (the implicit ACK, RFC 9147
+   * §7.1). The cookie-bearing ClientHello goes the same way.
+   */
+  function queueFlightMessage(tlsMsg, msgSeq, dtlsEpoch) {
+    ctx.flightMessagesQueued++;
+    ctx.flightQueued++;
+    if (ctx.flightBegan === null) ctx.flightBegan = Date.now();
+    if (ctx.rttStart === null && ctx.currentFlight.length === 0 && ctx.flightQueued === 1) ctx.rttStart = Date.now();
+    queueMessage(tlsMsg, msgSeq, dtlsEpoch, ctx.currentFlight, 'flight');
+  }
+
+  // What one record adds around its payload, by the epoch it goes out in
+  // (flushOut fills datagrams to the MTU with it):
+  //   unprotected (epoch 0, and DTLS 1.2 before the CCS): the 13-byte
+  //     DTLSPlaintext header, nothing else;
+  //   DTLS 1.3 protected: the unified header (1 + 2-byte sequence number +
+  //     2-byte length), the inner content-type byte, the 16-byte tag;
+  //   DTLS 1.2 protected: 13 + the 16-byte tag + the 8-byte explicit nonce
+  //     of AES-GCM / CCM (ChaCha20-Poly1305 has none, RFC 7905 §2);
+  //   and, with the peer's CID, the CID — and in 1.2 the inner type byte.
+  // A single figure for all — 37, or 21 for 1.3 — left 24 bytes unused in
+  // every plaintext fragment (the whole DTLS 1.2 certificate flight), and
+  // was a byte short for 1.3, which forgot the content type.
+  function recordOverhead(epoch) {
+    if (!ctx.keys[epoch] || !ctx.keys[epoch].write) return 13;
+    let cid = peerCid(), cidLen = cid ? cid.length : 0;
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) return 5 + cidLen + 1 + 16;
+    // The explicit nonce, as the suite table has it (record_ivlen).
+    let meta = TLS_CIPHER_SUITES[tls.getCipher()];
+    return 13 + (cid ? cidLen + 1 : 0) + 16 + (meta && meta.record_ivlen ? meta.record_ivlen : 0);
+  }
+
+  // DTLS 1.2, a ticket offered with no session_id (a hello offering DTLS
+  // 1.3 too): an epoch-1 record before any keys is the resumed server's
+  // ChangeCipherSpec or Finished — a full handshake has none before our
+  // flight. Tried under the keys the saved session gives; one that opens
+  // takes the resumption (tls.commitResume12), and the keys are installed.
+  // One that does not — anyone may send a datagram — changes nothing.
+  function tryResumedKeys12(record) {
+    let ms = tls.resumeCandidate12();
+    if (!ms) return;
+    let d12;
+    try { d12 = keys12(ms); } catch (e) { return; }
+    let opened;
+    try { opened = openDtls12(record.content, { key: d12.readKey, iv: d12.readIv }, record.epoch, record.seq, record.type, localCid()); }
+    catch (e) { return; }
+    if (!tls.commitResume12() || !installKeys12()) return;
+    open12(record, ctx.keys[1].read, opened);
+  }
+
+  // A DTLS 1.2 record of an epoch whose keys came after the datagram was
+  // parsed, opened now (or `opened` already: { type, content }), and through
+  // the replay window, as the datagram parser does. False when it does not
+  // open; one that opens and is malformed inside is the peer's (alertDesc).
+  function open12(record, readKeys, opened) {
+    try {
+      opened = opened || openDtls12(record.content, readKeys, record.epoch, record.seq, record.type, localCid());
+    } catch (e) { if (e && e.alertDesc) throw e; return false; }
+    record.type = opened.type;
+    record.content = opened.content;
+    record.encrypted = true;
+    if (!acceptRecordSeq(readKeys, record.seq)) record.replayed = true;
+    return true;
+  }
+
+  // DTLS 1.2: epoch 1's keys, from a master secret — the session's, once
+  // there is one, or a candidate's (tryResumedKeys12). One place: they were
+  // derived in three.
+  function keys12(masterSecret) {
+    let ts = tls.getTrafficSecrets();
+    return deriveKeys12(masterSecret, ts.localRandom, ts.remoteRandom, tls.getCipher(), isServer);
+  }
+  // …installed, once there is a master secret to make them of. True when
+  // they are there.
+  function installKeys12() {
+    if (ctx.keys[1]) return true;
+    let ts = tls.getTrafficSecrets();
+    if (!ts.masterSecret) return false;
+    let d12 = keys12(ts.masterSecret);
+    ctx.keys[1] = {
+      write: { key: d12.writeKey, iv: d12.writeIv },
+      read:  { key: d12.readKey,  iv: d12.readIv },
+    };
+    ctx.writeSeq[1] = 0;
+    return true;
+  }
+
+  // DTLS 1.3: the application epoch we write — 3 until a KeyUpdate moves it on.
+  function appEpoch() { return ctx.writeEpoch !== null ? ctx.writeEpoch : 3; }
+
+  /**
+   * The epoch our alerts (and close_notify) go out in: the highest one we
+   * hold write keys for and the peer reads. DTLS 1.3: the live application
+   * epoch once connected — after a KeyUpdate that is 4, 5, ..., and the peer
+   * no longer reads 3 — else the handshake epoch once its keys exist, else 0
+   * (a DTLSPlaintext record). DTLS 1.2: epoch 1 once our ChangeCipherSpec
+   * has gone, else 0.
    */
-  function fragmentMessage(dtlsMsg, tlsMsg, msgSeq) {
-    // Record-layer overhead we must leave room for inside one datagram/MTU:
-    //   DTLS 1.2: 13-byte classic record header + 16-byte AEAD tag (+8 explicit
-    //             nonce for GCM, but that lives inside the encrypted payload the
-    //             record layer builds, so we keep a small safety margin).
-    //   DTLS 1.3: 5-byte unified header (2-byte seq + length) + 16-byte AEAD tag.
-    // Using the correct, smaller 1.3 overhead avoids over-fragmenting.
-    let isDtls13 = ctx.selectedVersion === DTLS_VERSION.DTLS1_3;
-    let recordOverhead = isDtls13 ? (5 + 16) : (13 + 16 + 8);
-    let maxFragment = ctx.mtu - recordOverhead;
-
-    // The DTLS handshake message header is 12 bytes; the body is what we chunk.
-    const HS_HDR = 12;
-    if (dtlsMsg.length <= maxFragment) return [dtlsMsg];
-
-    // Need to fragment: split the TLS body into chunks
-    let body = tlsMsg.subarray(4); // skip TLS header (type+length)
-    let totalLength = body.length;
-    let fragments = [];
-    let offset = 0;
-
-    // Each fragment carries its own 12-byte handshake header, so the payload
-    // budget per fragment is maxFragment - HS_HDR.
-    let maxChunk = Math.max(1, maxFragment - HS_HDR);
-    while (offset < totalLength) {
-      let chunkLen = Math.min(maxChunk, totalLength - offset);
-      let frag = build_dtls_handshake(tlsMsg, msgSeq, offset, chunkLen);
-      fragments.push(frag);
-      offset += chunkLen;
-    }
-
-    return fragments;
+  function alertEpoch() {
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) {
+      if (ctx.state === 'connected' && ctx.writeEpoch !== null && ctx.keys[ctx.writeEpoch] && ctx.keys[ctx.writeEpoch].write) return ctx.writeEpoch;
+      if (ctx.keys[2] && ctx.keys[2].write) return 2;
+      return 0;
+    }
+    return (ctx.localCcsSent && ctx.keys[1] && ctx.keys[1].write) ? 1 : 0;
   }
 
   /**
    * Send an alert record.
    */
   function sendAlertRecord(epoch, alertData) {
+    // What is queued goes first, the alert in a datagram of its own (see
+    // flushOut).
+    flushOut();
     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;
-    _ldbgTx(record, 'L664'); ev.emit('packet', record);
+    _ldbgTx(record, 'alert'); ev.emit('packet', record);
   }
 
   /**
@@ -892,7 +1218,6 @@ function DTLSSession(options) {
       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
@@ -900,8 +1225,16 @@ function DTLSSession(options) {
     // 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]) });
-    _ldbgTx(record, 'L688'); ev.emit('packet', record);
+    //
+    // Into the flight where it goes out, as the messages' fragments are
+    // (flushOut): the messages queued before it — the ClientKeyExchange, a
+    // Certificate — are cut into entries only then, and a CCS put in the
+    // list here, at once, went ahead of them. Every retransmission then
+    // opened with the CCS (BoGo DTLS-RetransmitFinished-Fragmented: "record
+    // of type 20 in retransmit, but expected 22"); a peer that reads in
+    // order takes it before the key exchange it follows.
+    let ccs = { epoch: 0, contentType: CT.CHANGE_CIPHER_SPEC, payload: new Uint8Array([1]), list: ctx.currentFlight };
+    queueOut({ kind: 'entry', entry: ccs, label: 'ccs', join: true });
   }
 
 
@@ -909,7 +1242,67 @@ function DTLSSession(options) {
   //  Incoming: UDP datagram → parse → feed TLSSession
   // ============================================================
 
+  /**
+   * The one way a DTLS session ends in failure: our alert (when there is one
+   * to send — none when the peer's alert or TLSSession's own already went),
+   * the session closed (no more input, no retransmission), 'error', then
+   * 'close'. 'close' is what DTLSServer drops the connection on: a session
+   * that only emitted 'error' stayed in its table, deaf, and the address
+   * could not start a new handshake.
+   */
+  function fail(err, alertDesc) {
+    if (ctx.state === 'closed') return;
+    if (alertDesc !== undefined && alertDesc !== null) {
+      try { tls.sendAlert(2, alertDesc); } catch (e) {}
+      err = local_alert_error(alertDesc, err);
+    }
+    shutDown();
+    ev.emit('error', err);
+    ev.emit('close');
+  }
+
+  /**
+   * The input boundary: nothing a peer sends may throw out of this session
+   * (a single UDP datagram, spoofable by anyone, took the process down —
+   * BoGo). What cannot be read as a record is dropped where it is read, as
+   * RFC 9147 §4.5.2 / RFC 6347 §4.1.2.7 ask ("invalid records SHOULD be
+   * silently discarded"); what is left to throw here comes from a record
+   * that WAS read, or from a bug, and ends the session — the error's own
+   * alert (alertDesc), internal_error otherwise. TLSSession has the same
+   * boundary for what reaches it (run_guarded).
+   */
+  //
+  // Returns whether the datagram held a record that authenticated and is
+  // the newest yet (by epoch, then sequence number) — RFC 9146 §6 / RFC
+  // 9147 §9's condition for taking a new peer address, which the layer
+  // above decides.
   function feedDatagram(data) {
+    ctx.dgNewest = false;
+    try {
+      feedDatagramUnguarded(data);
+    } catch (e) {
+      let err = e instanceof Error ? e : new Error(String(e));
+      fail(err, (e && e.alertDesc) || TLS_ALERT.INTERNAL_ERROR);
+      return false;
+    }
+    return ctx.dgNewest;
+  }
+
+  // A protected record taken: the newest so far?
+  function noteNewest(record) {
+    let n = ctx.rxNewest;
+    if (n && (record.epoch < n.epoch || (record.epoch === n.epoch && record.seq <= n.seq))) return;
+    ctx.rxNewest = { epoch: record.epoch, seq: record.seq };
+    ctx.dgNewest = true;
+  }
+
+  function feedDatagramUnguarded(data) {
+    ctx.feeding++;
+    try { takeDatagram(data); }
+    finally { if (--ctx.feeding === 0) flushHeldPostHandshake(); }
+  }
+
+  function takeDatagram(data) {
     if (ctx.state === 'closed') return;
     if (ctx.state === 'idle') ctx.state = 'handshaking';
 
@@ -921,7 +1314,7 @@ function DTLSSession(options) {
       }
     }
 
-    let records = parseDtlsDatagram(data, keysByEpoch);
+    let records = parseDtlsDatagram(data, keysByEpoch, localCid(), localCidRequired());
 
     if (LEMON_DEBUG) {
       var _summ = [];
@@ -935,9 +1328,9 @@ function DTLSSession(options) {
     }
 
     // RFC 9147 §7: collect the record numbers of handshake records we received
-    // in this datagram so we can ACK them once, after processing. Only for
-    // DTLS 1.3, and only while we're still handshaking (post-handshake ACKs of
-    // NewSessionTicket etc. are optional and skipped here for simplicity).
+    // in this datagram so we can ACK them once, after processing (DTLS 1.3):
+    // a flight's at once or a quarter-timer later, post-handshake ones
+    // together, delayed (see "ACKs" below).
     let ackable = [];
 
     // Whether these records arrived AFTER the handshake must be decided here,
@@ -948,8 +1341,27 @@ function DTLSSession(options) {
     // the spurious epoch-3 ACK that makes a peer answer decode_error on the
     // NEXT record — so a perfectly good SCTP COOKIE_ECHO takes the blame.
     let wasConnectedOnEntry = (ctx.state === 'connected');
+    let sentBefore = ctx.flightMessagesQueued;
+    ctx.ackDisruption = false;
+    ctx.dgAnyNew = false;
+    ctx.dgDuplicate = false;
+    ctx.dgNewest = false;
 
     for (let i = 0; i < records.length; i++) {
+      // An unprotected record received before — same epoch-0 sequence number
+      // — is the same record again (replayed, or duplicated on the way), not
+      // the peer retransmitting: a retransmission is a new record, with a new
+      // number. Taken as one, it had us resend our flight (BoGo
+      // DTLS-Replay-TLS12). Not a sliding window, as for protected records
+      // (acceptRecordSeq): an unauthenticated number must not move one — a
+      // forged high one would make every real record "too old". Just the
+      // last numbers seen.
+      if (records[i].epoch === 0 && !records[i].encrypted) {
+        if (ctx.seenPlainSeqs.indexOf(records[i].seq) >= 0) continue;
+        ctx.seenPlainSeqs.push(records[i].seq);
+        if (ctx.seenPlainSeqs.length > 64) ctx.seenPlainSeqs.shift();
+      }
+      if (records[i].replayed) continue;
       // 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,
@@ -960,7 +1372,9 @@ function DTLSSession(options) {
         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; }
+        // A record that opened but is malformed inside (alertDesc) is the
+        // peer's: to the boundary. Anything else: it did not open, dropped.
+        try { dec = decryptEncryptedDtls13(records[i].raw, readKeys, records[i].epoch, localCid(), localCidRequired()); } catch (e) { if (e && e.alertDesc) throw e; dec = null; }
         if (!dec) continue;
         records[i] = {
           type: dec.type, epoch: dec.epoch, seq: dec.seq,
@@ -984,65 +1398,122 @@ function DTLSSession(options) {
         ackable.push({ epoch: records[i].epoch, seq: records[i].seq });
       }
 
+      let hadKeys12 = !!ctx.keys[1];
+      if (!hadKeys12 && ctx.selectedVersion === DTLS_VERSION.DTLS1_2 && records[i].epoch === 1 && !records[i].encrypted) {
+        tryResumedKeys12(records[i]);
+      }
       processRecord(records[i]);
+      if (ctx.state === 'closed') break;
+      if (records[i].encrypted) noteNewest(records[i]);
+      if (ctx.selectedVersion === DTLS_VERSION.DTLS1_2 && !ctx.keys[1]) installKeys12();
 
-      // After CCS, keys are newly available — re-decrypt remaining epoch>0 records
-      if (records[i].type === CT.CHANGE_CIPHER_SPEC && ctx.keys[1]) {
+      // DTLS 1.2 keys just installed: what of this datagram came protected
+      // under them can be read now.
+      if (!hadKeys12 && ctx.keys[1]) {
         let readKeys = ctx.keys[1].read;
         for (let j = i + 1; j < records.length; j++) {
-          if (!records[j].encrypted && records[j].epoch > 0 && readKeys) {
-            try {
-              records[j].content = decryptDtls12(records[j].content, readKeys.key, readKeys.iv, records[j].epoch, records[j].seq, records[j].type);
-              records[j].encrypted = true;
-            } catch(e) {
-            }
-          }
+          if (!records[j].encrypted && records[j].epoch > 0 && readKeys) open12(records[j], readKeys);
         }
       }
     }
 
-    // Send a single ACK covering all handshake records received in this datagram.
-    // We ACK from the highest epoch for which we already have write keys (so the
-    // ACK itself is protected once handshake keys exist; epoch 0 before that).
-    if (ackable.length > 0) {
-      // ACKs RIDE THE HANDSHAKE EPOCH (RFC 9147 §7): they acknowledge
-      // handshake records, so epoch 2 once handshake keys exist and
-      // epoch 0 before that — never epoch 3. Picking "the highest epoch
-      // we have keys for" sent them under APPLICATION-DATA protection,
-      // where the peer decrypts with app keys and finds a content type
-      // that does not belong. Chrome answers decode_error.
-      // This shows up the moment a ClientHello is large enough to be
-      // FRAGMENTED — an SFU with several transceivers crosses the MTU
-      // and a two-way call does not, which is exactly why bidirectional
-      // worked and party mode did not.
-      // Post-handshake (§7.1: "For post-handshake messages, ACKs SHOULD be
-      // sent once for each received and processed handshake record") the
-      // handshake epoch is gone and §7 requires the HIGHEST available sending
-      // epoch. During the handshake it is still epoch 2, or 0 before keys.
-      // RFC 9147 §7.1 lists the flights that are IMPLICITLY acknowledged by
-      // the responding flight, and the client's final flight is pointedly not
-      // among them: "In general, flights MUST be ACKed unless they are
-      // implicitly acknowledged", excepting "handshake flights other than the
-      // client's final flight of the main handshake".
-      //
-      // So the two roles need opposite answers here, which is why a
-      // state-only test could not get both right:
-      //   client — the server's flight is implicitly acked by our own final
-      //            flight, so an explicit ACK is both redundant and (at the
-      //            application epoch) actively harmful;
-      //   server — the client's final flight has no responding flight, so
-      //            without an explicit ACK the client retransmits it forever.
-      // §7 then fixes the epoch: after the handshake, the highest available
-      // sending epoch.
-      let justCompleted = (!wasConnectedOnEntry && ctx.state === 'connected');
-      let finalFlightAck = isServer && justCompleted;
-      let atAppEpoch = wasConnectedOnEntry || finalFlightAck;
-
-      let ackEpoch = atAppEpoch
-        ? (ctx.writeEpoch !== null ? ctx.writeEpoch : 3)
-        : (ctx.keys[2] ? 2 : 0);
-      sendAck(ackEpoch, ackable, atAppEpoch);
+    dtls12AnswerRetransmission();
+
+    // ── ACKs (RFC 9147 §7.1) ──
+    // Post-handshake records (NewSessionTicket, KeyUpdate, or the client's
+    // final flight again, its ACK lost): nothing answers them, so they are
+    // ACKed — at the highest sending epoch (§7) — but not each at once: one
+    // ACK a quarter of the timer later covers all that came meanwhile (§7.1,
+    // "implementations SHOULD [...] delay sending ACKs"; a server's two
+    // tickets, two records each, were four ACKs).
+    if (wasConnectedOnEntry) {
+      for (let ai = 0; ai < ackable.length; ai++) noteAck(ctx.postAcks, ackable[ai]);
+      if (ctx.postAcks.length > 0 && ctx.postAckTimer === null) {
+        ctx.postAckTimer = setTimeout(function () {
+          ctx.postAckTimer = null;
+          if (ctx.state === 'closed' || ctx.postAcks.length === 0) return;
+          let all = ctx.postAcks; ctx.postAcks = [];
+          sendAck(appEpoch(), all, true);
+        }, ackDelay(currentRto()));
+        if (ctx.postAckTimer.unref) ctx.postAckTimer.unref();
+      }
+      return;
+    }
+    for (let ai = 0; ai < ackable.length; ai++) noteAck(ctx.pendingAcks, ackable[ai]);
+    if (ctx.pendingAcks.length === 0) return;
+
+    // The client's final flight, now complete (the handshake is): nothing of
+    // ours answers it (a NewSessionTicket that follows is no answer — it is
+    // checked first for that reason), so it is ACKed explicitly, at once — §7.1 "MUST send
+    // ACKs upon receiving all of any flight which they do not respond to" —
+    // at the highest sending epoch, now the application one (§7).
+    if (isServer && ctx.state === 'connected') {
+      let all = ctx.pendingAcks; clearPendingAcks();
+      sendAck(appEpoch(), all, true);
+      return;
+    }
+    // The flight is complete and we answered it: our flight is the ACK
+    // (implicit). Sending one as well is what the RFC asks us not to do —
+    // "ACKs SHOULD NOT be sent for these complete flights" — and what BoGo
+    // saw: an ACK for every datagram of a flight, landing where the peer
+    // does not expect one.
+    if (ctx.flightMessagesQueued > sentBefore) { clearPendingAcks(); return; }
+
+    if (ctx.state !== 'handshaking') { clearPendingAcks(); return; }
+
+    // Part of a flight. A sign it is disrupted — a message or fragment out
+    // of order — is ACKed now, so the peer resends only what is missing;
+    // otherwise a timer of a quarter of the retransmit timeout (§7.1's
+    // suggestion) gives the rest of the flight time to arrive.
+    if (ctx.ackDisruption) {
+      cancelAckTimer();
+      sendHandshakeAck();
+    } else if (ctx.ackTimer === null) {
+      ctx.ackTimer = setTimeout(function () {
+        ctx.ackTimer = null;
+        if (ctx.state === 'handshaking' && ctx.pendingAcks.length > 0) sendHandshakeAck();
+      // A quarter of the retransmit timer (§7.1) — its initial value: the
+      // timer's backoff counts losses of OUR earlier flight (a ClientHello
+      // resent until the ServerHello came), which say nothing about how long
+      // the rest of the peer's flight may take. Read off the backed-off timer
+      // it was 2 s after three lost ClientHellos.
+      }, ackDelay(Math.min(ctx.retransmitTimeout, currentRto())));
+      if (ctx.ackTimer.unref) ctx.ackTimer.unref();
+    }
+  }
+
+  // How long an ACK waits: a quarter of the retransmit timer (§7.1's
+  // suggestion), a millisecond at least.
+  function ackDelay(rto) { return Math.max(1, Math.floor(rto / 4)); }
+  // A record to ACK, kept in `list`: the records of the peer's flight in
+  // progress (pendingAcks), ACKed cumulatively — each ACK lists all of them
+  // received so far (§7.1 "the messages from that flight which it has
+  // received and processed so far") — or post-handshake ones (postAcks);
+  // either way, up to what fits in one ACK record: its header (13), the
+  // record numbers' length (2) and an AEAD tag's worth (22) out of the MTU,
+  // 16 bytes a record number (RFC 9147 §7).
+  function noteAck(list, rn) {
+    for (let i = 0; i < list.length; i++) {
+      if (list[i].epoch === rn.epoch && list[i].seq === rn.seq) return;
     }
+    list.push(rn);
+    let room = Math.max(1, Math.floor((ctx.mtu - 13 - 22 - 2) / 16));
+    if (list.length > room) list.splice(0, list.length - room);
+  }
+  function cancelAckTimer() {
+    if (ctx.ackTimer !== null) { clearTimeout(ctx.ackTimer); ctx.ackTimer = null; }
+  }
+  function clearPendingAcks() {
+    cancelAckTimer();
+    ctx.pendingAcks = [];
+    if (ctx.postAckTimer !== null) { clearTimeout(ctx.postAckTimer); ctx.postAckTimer = null; }
+    ctx.postAcks = [];
+  }
+  // During the handshake: the handshake epoch (2), never 0 — only protected
+  // records are ever ACKed (the first flight never is).
+  function sendHandshakeAck() {
+    if (!ctx.keys[2]) return;
+    sendAck(2, ctx.pendingAcks.slice(), false);
   }
 
   function processRecord(record) {
@@ -1060,6 +1531,23 @@ function DTLSSession(options) {
     if (ctx.state === 'connected' && !record.encrypted &&
         (record.type === CT.ALERT || record.type === CT.APPLICATION_DATA)) return;
 
+    if (record.type !== CT.ALERT) ctx.consecutiveWarnings = 0;
+
+    // A record that opened under its keys is the peer's: more plaintext
+    // than a record may carry — 2^14 (RFC 8446 §5.1, RFC 5246 §6.2.1), or
+    // our record_size_limit once negotiated (RFC 8449 §4) — is
+    // record_overflow, as in TLS. Without a limit agreed, nothing was
+    // checked at all (BoGo LargePlaintext-DTLS). An unprotected one is
+    // anyone's: what arrives too long is dropped as the datagram is parsed
+    // (record.js).
+    if (record.encrypted && record.content) {
+      let rsl = tls.getRecordSizeLimit(), max = rsl ? rsl.receive : MAX_RECORD_PLAINTEXT;
+      if (record.content.length > max) {
+        throw parseError('DTLS record of ' + record.content.length + ' bytes, more than ' +
+          (rsl ? 'our record_size_limit (' + max + ')' : '2^14'), TLS_ALERT.RECORD_OVERFLOW);
+      }
+    }
+
     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
@@ -1076,42 +1564,81 @@ function DTLSSession(options) {
       processHandshakeRecord(record.content, record.epoch, record.encrypted);
     } else if (record.type === CT.APPLICATION_DATA) {
       if (ctx.state === 'connected') {
-        // Protected data from the peer means it completed the handshake,
-        // so it has our Finished.
-        if (ctx.finalFlightPending) finalFlightDone();
-        ev.emit('data', record.content);
+        // DTLS 1.2: protected data from the peer means it has our final
+        // flight — nothing more to answer its retransmissions with.
+        //
+        // NOT DTLS 1.3's final flight (finalFlightPending): that one is
+        // acknowledged by an ACK alone (RFC 9147 §7.1: it is the one flight
+        // not implicitly acknowledged, and "flights MUST be ACKed unless
+        // they are implicitly acknowledged"). A server sends data before it
+        // has our Finished — half-RTT data, its tickets — so its data said
+        // nothing of our Finished, and taken for it, a lost Finished was
+        // never resent: the server's handshake never ended (BoGo
+        // DTLS-Retransmit-Client-NoImplictACKFinished). A peer that never
+        // ACKs costs only the retransmissions: when they run out the flight
+        // is let go, the connection kept (startRetransmitTimer).
+        ctx.lastFlight12 = null;
+        // A Buffer, as node:tls gives (and every other buffer this API hands
+        // out): a view of the decrypted record, not a copy.
+        let c = record.content;
+        ev.emit('data', Buffer.isBuffer(c) ? c : Buffer.from(c.buffer, c.byteOffset, c.byteLength));
       }
     } else if (record.type === CT.CHANGE_CIPHER_SPEC) {
-      // DTLS 1.2: peer sent CCS — derive keys if not yet done
-      ctx.remoteCcsSeen = true;
-      if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 && !ctx.keys[1]) {
-        let ts = tls.getTrafficSecrets();
-        if (ts.masterSecret) {
-          let d12 = deriveKeys12(ts.masterSecret, ts.localRandom, ts.remoteRandom, tls.getCipher(), isServer);
-          ctx.keys[1] = {
-            write: { key: d12.writeKey, iv: d12.writeIv },
-            read:  { key: d12.readKey,  iv: d12.readIv },
-          };
-          ctx.writeSeq[1] = 0;
-        }
-      }
+      // One byte, 1 (RFC 6347 §4.1, RFC 5246 §7.1), and DTLS 1.2 only — DTLS
+      // 1.3 has none (RFC 9147 §5: not sent, and none is a key change here).
+      // Anything else changed our read state all the same. It is an
+      // unprotected record that does not read as one: dropped (§4.1.2.7).
+      if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) return;
+      if (!record.content || record.content.length !== 1 || record.content[0] !== 1) return;
+      // DTLS 1.2: the peer's key change. The keys come of the master
+      // secret, and are installed when it exists (installKeys12, after each
+      // record) — a CCS ahead of the key exchange (reordered: RFC 6347 §4.1),
+      // or one lost, changes nothing: no alert that would end a good
+      // handshake on one reordered datagram, and no flight resent for it
+      // either (DTLS-Fuzzer D5). A Finished must still come protected
+      // (epochFitsHandshake): the key change is proved by it, not by this.
+      installKeys12();
     } else if (record.type === CT.ACK) {
-      processAck(record.content);
+      // DTLS 1.3 only (RFC 9147 §7). One that does not parse: protected, the
+      // peer's (decode_error, thrown to the boundary); unprotected, dropped.
+      if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) return;
+      let acks;
+      try { acks = parseDtlsAck(record.content); }
+      catch (e) { if (!record.encrypted) return; throw e; }
+      processAck(acks);
     } else if (record.type === CT.ALERT) {
-      let level = record.content[0];
-      let desc = record.content[1];
+      // As TLS over TCP reads it (wire.read_peer_alert). A malformed one:
+      // protected, the alert for it; unprotected — anyone can send a
+      // datagram — dropped.
+      let a = read_peer_alert(record.content, ctx.selectedVersion === DTLS_VERSION.DTLS1_3);
+      if (a.error) {
+        if (!record.encrypted) return;
+        throw parseError('DTLS ' + a.error.message, a.error.alert);
+      }
+      let desc = a.desc;
       // Name the alert either way. A close_notify is a CLEAN shutdown and
       // a failure is not, but both present to the application as "the
       // connection ended" — and telling them apart is the difference
       // between "the peer hung up" and "the peer rejected us".
-      _ldbg('RX Alert level=' + level + ' desc=' + desc +
-            (desc === 0 ? ' (close_notify — clean shutdown)' : ' (failure)'));
-      if (desc === 0) {
-        // close_notify
-        ctx.state = 'closed';
-        ev.emit('close');
+      _ldbg('RX Alert level=' + a.level + ' desc=' + desc +
+            (desc === TLS_ALERT.CLOSE_NOTIFY ? ' (close_notify — clean shutdown)' : ' (failure)'));
+      ev.emit('alert', { level: a.level, description: desc });
+      if (desc === TLS_ALERT.CLOSE_NOTIFY) {
+        // close_notify — answered with ours (RFC 5246 §7.2.1: "The other
+        // party MUST respond with a close_notify alert of its own"; RFC 8446
+        // §6.1 the same, in effect: each side closes its write side with
+        // one). close() sends it and ends the session. It was not answered.
+        close();
+      } else if (!a.fatal) {
+        // A warning (user_canceled among them): the connection goes on. A
+        // run of them is not progress.
+        if (++ctx.consecutiveWarnings > MAX_WARNING_ALERTS) {
+          throw parseError('DTLS: too many consecutive warning alerts', TLS_ALERT.UNEXPECTED_MESSAGE);
+        }
       } else {
-        ev.emit('error', new Error('DTLS alert: level=' + level + ' desc=' + desc));
+        // Fatal: the session ends; it used to report and carry on,
+        // retransmitting.
+        fail(peer_alert_error(desc));   // as TLS over TCP reports it
       }
     }
   }
@@ -1124,8 +1651,25 @@ function DTLSSession(options) {
     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));
+    // A handshake fragment lies wholly inside its record (RFC 6347 §4.2.3,
+    // RFC 9147 §5.5: fragments are not split across records). One that does
+    // not — its 12-byte header cut short, or its body running past the end
+    // — is decode_error: the record itself read fine, the handshake inside
+    // it is malformed (§4.5.2's silent discard is for records that do not
+    // read as records). Dropping it left the session waiting for good (BoGo
+    // SplitFragments-Header/Body/Boundary). Except for an unprotected record
+    // once we are connected: then it can only be a stray retransmission or
+    // anyone's (spoofed) datagram, and one must not end the connection — it
+    // is dropped, as an unprotected ACK or alert is.
+    let strict = encrypted || ctx.state !== 'connected';
+    while (off < data.length) {
+      if (data.length - off < 12) {
+        if (!strict) return;
+        throw parseError('DTLS: a handshake fragment header cut short (' + (data.length - off) + ' bytes) at the end of its record', TLS_ALERT.DECODE_ERROR);
+      }
+      let parsed;
+      try { parsed = parse_dtls_handshake(data.subarray(off)); }   // decode_error when the body runs past
+      catch (e) { if (!strict) return; throw e; }
 
       let msgSeq = parsed.msg_seq;
       let totalLen = parsed.length;
@@ -1139,10 +1683,10 @@ function DTLSSession(options) {
       // Is this a complete message or a fragment?
       if (fragOffset === 0 && fragLen === totalLen) {
         // Complete message — feed directly
-        if (deliverHandshakeMessage(parsed.type, parsed.body, msgSeq)) anyNew = true;
+        if (deliverHandshakeMessage(parsed.type, parsed.body, msgSeq, epoch)) anyNew = true;
       } else {
         // Fragment — reassemble
-        if (reassembleFragment(parsed)) anyNew = true;
+        if (reassembleFragment(parsed, epoch)) anyNew = true;
       }
 
       off += 12 + fragLen;
@@ -1167,28 +1711,42 @@ function DTLSSession(options) {
     // 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) {
+    // Whether this record carried only messages already taken — the
+    // peer retransmitting — is decided for the whole datagram, in
+    // feedDatagram (dtls12AnswerRetransmission): a datagram that also
+    // brings something new is progress, not a retransmission.
+    if (anyNew) ctx.dgAnyNew = true;
+    else if (sawMessage) ctx.dgDuplicate = true;
+  }
+
+  /**
+   * DTLS 1.2 (RFC 6347 §4.2.4): the peer retransmitting its last flight
+   * means it never got our answer — we resend ours at once, rather than
+   * waiting out our own timer. DTLS 1.3 has ACKs for this instead.
+   *
+   * After the handshake, too: the side that sent the LAST flight (the
+   * server's CCS + Finished in a full handshake) keeps it, and resends it
+   * when the peer's final flight comes again — the state machine's FINISHED
+   * state. It was dropped at 'connect', so a lost server Finished left the
+   * client retransmitting into a server that had nothing to say: the
+   * handshake never completed (BoGo Retransmit-*-TLS12; and 1 in 7 at 30%
+   * loss in dtls_loss_test). Kept until the peer's application data shows
+   * it finished.
+   */
+  function dtls12AnswerRetransmission() {
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_3) return;
+    if (!ctx.dgDuplicate || ctx.dgAnyNew) return;
+    // Damping: a peer retransmits its flight as SEVERAL datagrams; one
+    // resend per 250 ms answers the whole retransmitted flight once.
+    if ((Date.now() - (ctx._lastDupElicitedResend || 0)) < 250) return;
+    if (ctx.state === 'handshaking' && haveFlight()) {
       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.
+      // The regular timer keeps running unchanged, so the retransmit budget
+      // still bounds the total effort.
       resendFlight();
+    } else if (ctx.state === 'connected' && ctx.lastFlight12) {
+      ctx._lastDupElicitedResend = Date.now();
+      transmitUnacked(ctx.lastFlight12, 'lastFlight12', false);
     }
   }
 
@@ -1202,7 +1760,7 @@ function DTLSSession(options) {
    * merged byte-ranges, rather than requiring each fragment to start exactly
    * where the previous one ended.
    */
-  function reassembleFragment(parsed) {
+  function reassembleFragment(parsed, epoch) {
     let key = parsed.msg_seq;
 
     // Ignore fragments for messages we've already delivered.
@@ -1212,14 +1770,28 @@ function DTLSSession(options) {
     // fragment. Reject anything claiming more than our cap BEFORE allocating,
     // so a peer can't force huge buffers with a single unauthenticated packet.
     if (parsed.length > ctx.maxHandshakeMessageSize) {
-      ev.emit('error', new Error('DTLS handshake message exceeds maxHandshakeMessageSize (' +
-        parsed.length + ' > ' + ctx.maxHandshakeMessageSize + ')'));
-      return false;
+      // It was reported and the session carried on, waiting for a message
+      // it had refused. The same alert as TLS over TCP for an oversized
+      // message (illegal_parameter, as OpenSSL).
+      throw parseError('DTLS handshake message of ' + parsed.length + ' bytes, more than ' + ctx.maxHandshakeMessageSize, TLS_ALERT.ILLEGAL_PARAMETER);
     }
 
     let frag = ctx.fragments[key];
+    // Every fragment of one message names the same type and total length
+    // (RFC 6347 §4.2.3, RFC 9147 §5.5). One that disagrees with those
+    // already held was copied in anyway — or, past the buffer, dropped — and
+    // the message never completed: the session waited for good.
+    if (frag && frag.epoch !== epoch) {
+      // Half a message under one key and half under another (RFC 8446
+      // §5.1: handshake messages MUST NOT span key changes).
+      throw parseError('DTLS: message ' + key + ' in fragments of epochs ' + frag.epoch + ' and ' + epoch, TLS_ALERT.UNEXPECTED_MESSAGE);
+    }
+    if (frag && (frag.type !== parsed.type || frag.totalLength !== parsed.length)) {
+      throw parseError('DTLS: fragments of message ' + key + ' disagree on its type or length', TLS_ALERT.ILLEGAL_PARAMETER);
+    }
     if (!frag) {
       frag = ctx.fragments[key] = {
+        epoch: epoch,
         totalLength: parsed.length,
         type: parsed.type,
         buf: new Uint8Array(parsed.length),
@@ -1230,8 +1802,11 @@ function DTLSSession(options) {
     let start = parsed.frag_offset;
     let end = parsed.frag_offset + parsed.frag_length;
 
-    // Bounds guard against a malformed fragment claiming to exceed totalLength.
-    if (end > frag.totalLength) return false;
+    // A fragment past the message's end (parse_dtls_handshake already holds
+    // the body to frag_length; this is offset + length > the total).
+    if (end > frag.totalLength) {
+      throw parseError('DTLS: fragment ' + start + '+' + parsed.frag_length + ' runs past message length ' + frag.totalLength, TLS_ALERT.ILLEGAL_PARAMETER);
+    }
 
     // Coverage before this fragment — used to decide whether it contributed
     // anything new (a retransmitted fragment that only re-covers known bytes
@@ -1264,10 +1839,13 @@ function DTLSSession(options) {
     }
 
 
+    // A fragment past a hole: one before it is missing (§7.1).
+    if (merged.length > 1 || merged[0][0] !== 0) ctx.ackDisruption = true;
+
     // 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];
-      return deliverHandshakeMessage(frag.type, frag.buf, key);
+      return deliverHandshakeMessage(frag.type, frag.buf, key, frag.epoch);
     }
     return coveredAfter > coveredBefore;
   }
@@ -1282,12 +1860,19 @@ function DTLSSession(options) {
    *   dropped. processHandshakeRecord uses this for the implicit-ACK
    *   decision — only genuinely new data may cancel our retransmit timer.
    */
-  function deliverHandshakeMessage(type, body, msgSeq) {
+  function deliverHandshakeMessage(type, body, msgSeq, epoch) {
     // Skip if we've already processed this msg_seq (duplicate / retransmit).
     if (msgSeq < ctx.nextReadMsgSeq) return false;
 
     // Check for HelloVerifyRequest (DTLS 1.2 server→client, type=3)
     if (type === 3 && !isServer) {
+      // Only where one can come (RFC 6347 §4.2.1): unprotected, before any
+      // ServerHello, as the answer to a ClientHello (message_seq 0 or 1).
+      // Anywhere else it is no server's — and it was taken anywhere: one
+      // datagram, after our last flight or after the handshake, made the
+      // client start over (a new ClientHello, transcript and flights wiped).
+      // Dropped (D2).
+      if (epoch !== 0 || tls.context.remote_random != null || msgSeq > 1) return false;
       ctx.nextReadMsgSeq = msgSeq + 1;
       // The HVR acknowledges CH1 (implicit ACK, RFC 6347 §4.2.4). No
       // explicit cancel is needed: triggerClientHelloWithCookie arms the
@@ -1332,10 +1917,9 @@ function DTLSSession(options) {
       // '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(
+        fail(new Error(
           'DTLS 1.3 ClientHello carries a non-empty legacy_cookie (' +
-          ch.dtls_cookie.length + ' bytes) — RFC 9147 §5.3 requires zero length'));
+          ch.dtls_cookie.length + ' bytes) — RFC 9147 §5.3 requires zero length'), 47);
         return false;
       }
 
@@ -1344,7 +1928,12 @@ function DTLSSession(options) {
       // 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) {
+      // Only for the handshake's first ClientHello (nothing read yet): a
+      // later one with a valid cookie — the attacker's replay of the real
+      // one — reset the read cursor mid-handshake (or after it) and stalled
+      // it without a word (D3). Later, a ClientHello goes the normal way:
+      // in order, to the TLS state machine, which refuses it.
+      if (options.useCookies === true && !offersDtls13 && ctx.nextReadMsgSeq === 0) {
 
       let incomingCookie = (ch && ch.dtls_cookie) ? ch.dtls_cookie : new Uint8Array(0);
 
@@ -1393,9 +1982,12 @@ function DTLSSession(options) {
     // and wait for the gap to fill. If it's the next expected one, feed it, then
     // drain any consecutive messages that were buffered earlier.
     if (msgSeq > ctx.nextReadMsgSeq) {
+      // Out of order: a message is missing before it — the peer should
+      // learn now what arrived (an ACK, RFC 9147 §7.1).
+      ctx.ackDisruption = true;
       // Out of order — hold it (ignore a duplicate already buffered).
       if (!(msgSeq in ctx.pendingMessages)) {
-        ctx.pendingMessages[msgSeq] = { type: type, body: body };
+        ctx.pendingMessages[msgSeq] = { type: type, body: body, epoch: epoch };
         return true;    // new information, even if not yet deliverable
       }
       return false;     // duplicate of an already-buffered message
@@ -1426,6 +2018,8 @@ function DTLSSession(options) {
     //     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.
+    if (!epochFitsHandshake(epoch, type)) return false;
+    flightAnswered();
     startRetransmitTimer();
     ctx.newFlightPending = true;
     feedHandshakeToTls(type, body, msgSeq);
@@ -1440,6 +2034,9 @@ function DTLSSession(options) {
     while (ctx.nextReadMsgSeq in ctx.pendingMessages) {
       let next = ctx.pendingMessages[ctx.nextReadMsgSeq];
       delete ctx.pendingMessages[ctx.nextReadMsgSeq];
+      // Held while a message before it was missing — and that message may
+      // have changed the keys (a ServerHello): checked now, not when held.
+      if (!epochFitsHandshake(next.epoch, next.type)) break;
       startRetransmitTimer();
       ctx.newFlightPending = true;
       feedHandshakeToTls(next.type, next.body, ctx.nextReadMsgSeq);
@@ -1448,11 +2045,60 @@ function DTLSSession(options) {
     return true;
   }
 
+  /**
+   * DTLS 1.3: the epoch a handshake message must arrive in is the one the
+   * handshake is at when it is taken — 0 up to the ServerHello, 2 (the
+   * handshake keys) up to the peer's Finished, 3 and up after it (RFC 9147
+   * §6.1, RFC 8446 §5.1). A message held out of order was checked when it
+   * arrived, before the message ahead of it moved the keys: a plaintext
+   * message buffered behind a missing ServerHello was then taken as if it
+   * had come encrypted (BoGo: a key change with messages buffered).
+   * Unprotected, it may be anyone's, and is dropped (RFC 9147 §4.5.2) — the
+   * real one, protected, takes its place; protected, it is the peer's own
+   * doing: unexpected_message.
+   *
+   * DTLS 1.2 is not checked here: its key change is the peer's
+   * ChangeCipherSpec, which may arrive ahead of the ClientKeyExchange it
+   * depends on, and a protected message cannot be read before it anyway.
+   */
+  function epochFitsHandshake(epoch, type) {
+    if (typeof epoch !== 'number') return true;
+    if (ctx.selectedVersion === DTLS_VERSION.DTLS1_2) {
+      // DTLS 1.2 (RFC 6347 §4.1, RFC 5246 §7.1): Finished is the first
+      // message under the new keys — epoch 1. One in epoch 0 was taken: the
+      // handshake ended with no key change at all, the Finished in the clear
+      // (DTLS-Fuzzer D1; the CCS-injection family). Epoch 1 is the proof of
+      // the change — the record opened under the new keys — not the CCS
+      // record itself, which can be lost while the Finished behind it
+      // arrives (dtls_loss_test: requiring both failed a third of the
+      // handshakes at 15% loss). Messages before it may still come in epoch
+      // 0 after the CCS: reordered, a CertificateVerify can trail it.
+      if (type === 20 && epoch !== 1) {
+        throw parseError('DTLS 1.2: Finished in epoch ' + epoch + ' — it must come protected, after the key change', TLS_ALERT.UNEXPECTED_MESSAGE);
+      }
+      // After the handshake an unprotected handshake message is anyone's — a
+      // HelloVerifyRequest or ClientHello sent to tear the connection down
+      // (D2, D3): dropped. (Renegotiation would come protected, epoch 1.)
+      if (epoch === 0 && ctx.state === 'connected') return false;
+      return true;
+    }
+    if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3) return true;
+    let hsKeys = !!(ctx.keys[2] && ctx.keys[2].read);
+    let fits = !hsKeys ? epoch === 0 : (ctx.state === 'connected' ? epoch >= 3 : epoch === 2);
+    if (fits) return true;
+    if (epoch === 0) return false;
+    throw parseError('DTLS 1.3: a handshake message in epoch ' + epoch + ', where epoch ' +
+      (!hsKeys ? 0 : (ctx.state === 'connected' ? '3 or later' : 2)) + ' was due', TLS_ALERT.UNEXPECTED_MESSAGE);
+  }
+
   /**
    * Feed one in-order handshake message to the TLSSession, converting from DTLS
    * to TLS wire format and driving version detection.
    */
   function feedHandshakeToTls(type, body, msgSeq) {
+    // DTLS 1.3's own post-handshake messages: the TLS engine has no part in them.
+    if (type === TLS_MESSAGE_TYPE.REQUEST_CONNECTION_ID || type === TLS_MESSAGE_TYPE.NEW_CONNECTION_ID) { takeConnectionIdMessage(type, body); return; }
+
     // Build TLS-format message: type(1) + length(3) + body
     let tlsMsg = build_message(type, body);
 
@@ -1471,6 +2117,54 @@ function DTLSSession(options) {
     }
   }
 
+  /**
+   * RequestConnectionId / NewConnectionId (RFC 9147 §5.8, §9): DTLS 1.3,
+   * after the handshake, and only where CIDs were agreed to — a peer that
+   * did not, or asked for an empty one, "MUST NOT send" them
+   * (unexpected_message otherwise).
+   *
+   * NewConnectionId: CIDs to put in what we send. cid_immediate — the first
+   * of them, from now on (§9: the peer "wants the recipient to use" one of
+   * them at once); cid_spare — there for later: we have no reason to move,
+   * and are not obliged to.
+   * RequestConnectionId: "does not force the receiver to send a
+   * NewConnectionId": we give out one CID, the one agreed, and keep it.
+   * Both are ACKed, as any handshake record.
+   */
+  function takeConnectionIdMessage(type, body) {
+    let unexpected = function (why) { throw parseError(why, TLS_ALERT.UNEXPECTED_MESSAGE); };
+    let malformed = function (why) { throw parseError(why, TLS_ALERT.DECODE_ERROR); };
+    let name = type === TLS_MESSAGE_TYPE.NEW_CONNECTION_ID ? 'NewConnectionId' : 'RequestConnectionId';
+    if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 || ctx.state !== 'connected' || !ctx.cid) unexpected(name + ' without connection IDs agreed to');
+    if (type === TLS_MESSAGE_TYPE.REQUEST_CONNECTION_ID) {
+      if (body.length !== 1) malformed('RequestConnectionId is malformed');
+      if (ctx.cid.local.length === 0) unexpected('RequestConnectionId, and we asked for no CID');
+      return;
+    }
+    if (ctx.cid.peer.length === 0) unexpected('NewConnectionId from a peer that asked for no CID');
+    if (body.length < 3) malformed('NewConnectionId is malformed');
+    let listLen = (body[0] << 8) | body[1];
+    if (2 + listLen + 1 !== body.length) malformed('NewConnectionId is malformed');
+    let cids = [];
+    for (let off = 2; off < 2 + listLen;) {
+      let n = body[off];
+      if (n === 0 || off + 1 + n > 2 + listLen) malformed('NewConnectionId: an empty or truncated CID');
+      cids.push(body.slice(off + 1, off + 1 + n));
+      off += 1 + n;
+    }
+    let usage = body[2 + listLen];
+    if (usage > 1) throw parseError('NewConnectionId: usage ' + usage, TLS_ALERT.ILLEGAL_PARAMETER);
+    if (usage === 0 && cids.length > 0) {
+      ctx.cid = { local: ctx.cid.local, peer: new Uint8Array(cids[0]) };
+      ev.emit('connectionId', getConnectionIds());
+    }
+  }
+
+  // The Connection IDs as they are now: { local, peer }, or null.
+  function getConnectionIds() {
+    return ctx.cid ? { local: new Uint8Array(ctx.cid.local), peer: new Uint8Array(ctx.cid.peer) } : null;
+  }
+
   /**
    * Server: build and send a HelloVerifyRequest with a fresh cookie (DTLS 1.2).
    * The cookie is a CSPRNG value stored on the context; a matching cookie must
@@ -1484,8 +2178,7 @@ function DTLSSession(options) {
 
     // HVR always uses msg_seq 0 and is sent in the clear (epoch 0).
     let hvrMsg = build_dtls_handshake(build_message(3, build_hello_verify_request({ cookie: cookie })), 0);
-    let record = buildDtlsPlaintext(CT.HANDSHAKE, 0, nextWriteSeq(0), hvrMsg);
-    _ldbgTx(record, 'L1194'); ev.emit('packet', record);
+    queueOut({ kind: 'raw', epoch: 0, contentType: CT.HANDSHAKE, payload: hvrMsg, label: 'hvr' });
   }
 
   /**
@@ -1534,6 +2227,7 @@ function DTLSSession(options) {
     // a wire message sent with seq 1 would fail Finished verification.
     tls.context.message_sent_seq = 1;
     ctx.currentFlight = [];
+    ctx.flightQueued = 0;
     ctx.fragments = {};          // discard any partial reassembly from CH1 flight
     ctx.pendingMessages = {};    // discard any out-of-order buffer from CH1 flight
     transcriptMsgSeqs = [];
@@ -1545,11 +2239,9 @@ function DTLSSession(options) {
       tls.context.transcriptHook ? tls.context.transcriptHook(ch2) : ch2
     );
 
-    // 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 = [{ epoch: 0, contentType: CT.HANDSHAKE, payload: dtlsMsg }];
-    if (record) { _ldbgTx(record, 'L1258'); ev.emit('packet', record); }
+    // Send — msg_seq 1 per the RFC figure above — as every flight message
+    // goes: fragmented to the MTU, each fragment kept for retransmission.
+    queueFlightMessage(ch2, 1, 0);
 
     tls.context.message_sent_seq = 2;
     startRetransmitTimer();
@@ -1583,25 +2275,44 @@ function DTLSSession(options) {
       cancelRetransmit();
       return;
     }
-    for (let i = 0; i < ctx.currentFlight.length; i++) {
-      let f = ctx.currentFlight[i];
-      // DTLS 1.3 (RFC 9147 §7.1): records the peer has ACKed are not resent.
-      if (f.acked) continue;
-      let record = buildFlightRecord(f);
-      if (record) { _ldbgTx(record, 'L1280'); ev.emit('packet', record); }
-    }
+    // DTLS 1.3 (RFC 9147 §7.1): records the peer has ACKed are not resent.
+    ctx.flightResent = true;   // no RTT sample from it now (Karn)
+    transmitUnacked(ctx.currentFlight, 'flight-rtx', false);
   }
 
   /**
-   * Build the record for a flight entry and remember its record number
-   * (epoch, sequence) — every transmission gets a fresh one, and a DTLS 1.3
-   * ACK names the records it covers by those numbers.
+   * (Re)send the entries of a flight or post-handshake message that are not
+   * ACKed yet — in new records, with new numbers (flushOut). `skipPlaintext`:
+   * not the epoch-0 ones.
    */
-  function buildFlightRecord(f) {
-    let seq = (f.epoch in ctx.writeSeq) ? ctx.writeSeq[f.epoch] : 0;
-    let record = buildRecord(f.epoch, f.contentType, f.payload);
-    if (record) (f.sent || (f.sent = [])).push(f.epoch * 0x1000000000000 + seq);
-    return record;
+  function transmitUnacked(entries, label, skipPlaintext) {
+    for (let i = 0; i < entries.length; i++) {
+      let f = entries[i];
+      if (f.acked || (skipPlaintext && f.epoch === 0)) continue;
+      queueOut({ kind: 'entry', entry: f, label: label });
+    }
+  }
+
+  // A record number (RFC 9147 §4: epoch, sequence number) as one key — the
+  // way sent records and ACKs are matched up. A string: epoch * 2^48 + seq
+  // stops being exact past epoch 31 (2^53), which KeyUpdates reach, and two
+  // records' numbers would collide.
+  function recordNumber(epoch, seq) { return epoch + '/' + seq; }
+
+  // Entries (of a flight, or of a post-handshake message) an ACK covers:
+  // any of the records an entry went out in, its first sending or a
+  // retransmission, is in `got`.
+  // Returns how many it marked now.
+  function markAcked(entries, got) {
+    let newly = 0;
+    for (let i = 0; i < entries.length; i++) {
+      let e = entries[i];
+      if (e.acked || !e.sent) continue;
+      for (let k = 0; k < e.sent.length; k++) {
+        if (got.has(e.sent[k])) { e.acked = true; newly++; break; }
+      }
+    }
+    return newly;
   }
 
   function startRetransmitTimer() {
@@ -1613,16 +2324,16 @@ function DTLSSession(options) {
     // connected (or closed) covers every caller, including any added
     // later, without each having to remember the rule.
     if (ctx.state === 'closed' || (ctx.state === 'connected' && !ctx.finalFlightPending)) return;
+    if (ctx.flightBegan === null) ctx.flightBegan = Date.now();
     ctx.retransmitTimer = setTimeout(function() {
-      if (ctx.finalFlightPending && ctx.retransmitCount >= ctx.maxRetransmits) {
+      if (ctx.finalFlightPending && exhausted(ctx.retransmitCount, ctx.flightBegan)) {
         // The connection is up on our side; stop resending without failing it.
         finalFlightDone();
         return;
       }
-      if (ctx.retransmitCount >= ctx.maxRetransmits) {
-        ev.emit('error', new Error('DTLS handshake timeout — max retransmits exceeded'));
-        ctx.state = 'closed';
-        ev.emit('close');
+      if (exhausted(ctx.retransmitCount, ctx.flightBegan)) {
+        fail(new Error('DTLS handshake timeout — no answer after ' + ctx.retransmitCount +
+          ' retransmissions in ' + Math.round((Date.now() - ctx.flightBegan) / 1000) + ' s'));
         return;
       }
 
@@ -1651,10 +2362,54 @@ function DTLSSession(options) {
     }
   }
 
+  // Whether we have a flight out (or on its way out: its messages become
+  // entries of ctx.currentFlight only when packed, at the end of the pass).
+  // Asked of currentFlight alone, the client that had just queued its
+  // Finished found nothing to keep under the timer — and a lost Finished
+  // was never resent.
+  function haveFlight() { return ctx.currentFlight.length > 0 || ctx.flightQueued > 0; }
+
   function startNewFlight() {
     ctx.currentFlight = [];
+    ctx.flightQueued = 0;
     ctx.retransmitCount = 0;
-    ctx.retransmitTimeout = 1000;
+    ctx.retransmitTimeout = currentRto();
+    ctx.flightBegan = null;
+    ctx.rttStart = null;
+    ctx.flightResent = false;
+  }
+
+  // Where a timer starts: the initial value until there is a round-trip
+  // sample, then SRTT + 4·RTTVAR (RFC 6298 §2) — not under RTO_MIN_MS, not
+  // over 60 s. An initialRetransmitTimeout given (the option, or
+  // setInitialRetransmitTimeout) is a schedule the caller chose: it is kept
+  // — from it, doubling — and no round trip changes it (fixedRto).
+  //
+  // The floor was 50 ms. A loopback, or a peer that answers within the same
+  // tick, measures a round trip of 0, and a real path that once measured
+  // short then lost its next flight to a 50 ms timer. RFC 9147 sets no
+  // floor; 100 ms is WebRTC's own initial timer. And a fixed schedule
+  // matters to a peer that times itself by one (BoGo advances its clock by
+  // BoringSSL's 400 ms, 800 ms …: an adaptive 50 ms timer fired several
+  // times in each step).
+  function currentRto() {
+    if (ctx.fixedRto || ctx.srtt === null) return ctx.initialRetransmitTimeout;
+    return Math.max(RTO_MIN_MS, Math.min(60000, Math.round(ctx.srtt + 4 * ctx.rttvar)));
+  }
+  function sampleRtt(r) {
+    if (ctx.srtt === null) { ctx.srtt = r; ctx.rttvar = r / 2; }
+    else { ctx.rttvar = 0.75 * ctx.rttvar + 0.25 * Math.abs(ctx.srtt - r); ctx.srtt = 0.875 * ctx.srtt + 0.125 * r; }
+  }
+  // The peer's answer to our flight has begun (a new message of its next
+  // flight, or — DTLS 1.3 — an ACK of a protected record of ours).
+  function flightAnswered() {
+    if (ctx.rttStart !== null && !ctx.flightResent) sampleRtt(Date.now() - ctx.rttStart);
+    ctx.rttStart = null;
+  }
+  // Time to give up on what keeps going unanswered: tried enough, and long
+  // enough (maxRetransmits, giveUpAfter).
+  function exhausted(attempts, began) {
+    return attempts >= ctx.maxRetransmits && began !== null && Date.now() - began >= ctx.giveUpAfter;
   }
 
 
@@ -1662,20 +2417,13 @@ function DTLSSession(options) {
   //  ACK (DTLS 1.3)
   // ============================================================
 
-  function processAck(content) {
-    let acks = parseDtlsAck(content);
-
-    // An outstanding KeyUpdate is what this ACK is for: §8 forbids protecting
-    // anything with the new keys until it arrives, so THIS is the moment the
-    // new epoch becomes live. Keys were installed when the KeyUpdate was sent;
-    // only the switch happens here.
-    if (ctx.pendingWriteEpoch !== null) {
-      ctx.writeEpoch = ctx.pendingWriteEpoch;
-      ctx.pendingWriteEpoch = null;
-      cancelKeyUpdateRetransmit();
-      ev.emit('keyUpdate', { direction: 'send', epoch: ctx.writeEpoch });
-      return;
-    }
+  function processAck(acks) {
+    let got = new Set();
+    for (let i = 0; i < acks.length; i++) got.add(recordNumber(acks[i].epoch, acks[i].seq));
+
+    // Post-handshake messages first — a KeyUpdate's epoch switch among them.
+    if (ctx.postHandshake.length > 0) ackPostHandshake(got);
+    if (ctx.state === 'closed' || (ctx.state === 'connected' && !ctx.finalFlightPending)) return;
 
     // During the handshake an ACK may cover only PART of our flight (RFC 9147
     // §7.1): the peer lists the records it received. Those are done; the
@@ -1686,22 +2434,58 @@ function DTLSSession(options) {
     // (≈ half of all handshakes at 5% loss, when the lost record was inside
     // the server's flight).
     if ((ctx.state !== 'connected' || ctx.finalFlightPending) && ctx.currentFlight.length > 0) {
-      let got = new Set();
-      for (let i = 0; i < acks.length; i++) got.add(acks[i].epoch * 0x1000000000000 + acks[i].seq);
-      let remaining = 0;
+      let newly = markAcked(ctx.currentFlight, got);
+      if (newly > 0) flightAnswered();
+      let remaining = 0, protectedEntries = 0, protectedAcked = 0;
       for (let i = 0; i < ctx.currentFlight.length; i++) {
         let f = ctx.currentFlight[i];
-        if (!f.acked && f.sent) {
-          for (let k = 0; k < f.sent.length; k++) {
-            if (got.has(f.sent[k])) { f.acked = true; break; }
-          }
+        // Plaintext epoch-0 records (ClientHello, ServerHello) are never
+        // ACKed — the peer acknowledges them implicitly by answering — so
+        // they do not keep the flight open on their own.
+        if (f.epoch === 0) continue;
+        protectedEntries++;
+        if (f.acked) protectedAcked++; else remaining++;
+      }
+      // A flight of plaintext alone (a ClientHello) is answered, never
+      // ACKed: an ACK — an empty one, from a peer that could not read
+      // something of ours — confirms none of it, and ended its
+      // retransmission (the timer cancelled below), the ClientHello lost
+      // for good.
+      if (protectedEntries === 0) return;
+      if (remaining > 0) {
+        // RFC 9147 §7.2: "Upon receipt of an ACK that leaves it with only
+        // some messages from a flight having been acknowledged, an
+        // implementation SHOULD retransmit the unacknowledged messages or
+        // fragments." The peer ACKs a partial flight when it sees a gap, or
+        // after a quarter of its timer with the rest still missing — either
+        // way the rest is lost, and waiting for our own timer (doubled by
+        // every earlier loss: 8 s and more) stalled the handshake past its
+        // deadline (dtls_loss_test, 30% loss).
+        //
+        // At once when this ACK confirmed something new. One that confirms
+        // nothing new — a repeat, or an empty one (wolfSSL sends one for
+        // each record it cannot read: with our ServerHello lost, all of
+        // them) — at most once a quarter of the initial timer: resending on
+        // each, both sides fed each other 15 000–34 000 datagrams a second.
+        // Epoch-0 records go too while the peer has ACKed none of the
+        // protected ones — it may lack our ServerHello, and so the keys;
+        // once it has ACKed one, it has them.
+        let now = Date.now();
+        if (newly > 0 || now - ctx.lastAckResend >= ackDelay(currentRto())) {
+          ctx.lastAckResend = now;
+          ctx.flightResent = true;
+          transmitUnacked(ctx.currentFlight, 'partial-ack', protectedAcked > 0);
+          // The records just resent start their wait again: the timer, left
+          // as it was, fired soon after and sent the same records a second
+          // time — wasted on a real path, and packed with the first copy
+          // where both go out in one pass (BoGo DTLS-Retransmit-Server-
+          // ACKMatchingEpoch-TLS13: "excess data"). Its value is kept: this
+          // was no timeout.
+          startRetransmitTimer();
         }
-        // Plaintext epoch-0 records (ServerHello, CCS) are never ACKed — the
-        // peer acknowledges them implicitly by answering — so they do not
-        // keep the timer alive on their own.
-        if (!f.acked && f.epoch !== 0) remaining++;
+        return;
       }
-      if (remaining > 0) return;
+      if (newly === 0 && !ctx.finalFlightPending) return;   // nothing this ACK confirmed
     }
 
     // The whole flight is acknowledged — or, the ACK for the client's final
@@ -1735,8 +2519,7 @@ function DTLSSession(options) {
     if (!postHandshake && (ctx.state === 'connected' || ctx.state === 'closed')) return;
     if (ctx.state === 'closed') return;
     let payload = buildDtlsAck(recordsToAck);
-    let record = buildRecord(epoch, CT.ACK, payload);
-    _ldbgTx(record, 'L1334'); ev.emit('packet', record);
+    queueOut({ kind: 'raw', epoch: epoch, contentType: CT.ACK, payload: payload, label: 'ack' });
   }
 
 
@@ -1754,6 +2537,10 @@ function DTLSSession(options) {
     ev.emit('clienthello', data, message);
   });
 
+  // Agreed (the hello), or moved by the peer's NewConnectionId: the record
+  // layer's from now on, and the application's to know.
+  tls.on('connectionId', function(ids) { ctx.cid = ids; ev.emit('connectionId', getConnectionIds()); });
+
   tls.on('secureConnect', function() {
     _ldbg('handshake complete — secureConnect (version=0x' +
       ((ctx.selectedVersion || tls.context.selected_version || 0).toString(16)) + ')');
@@ -1763,10 +2550,17 @@ function DTLSSession(options) {
     // retransmit timer until that ACK — or anything else from the peer at
     // the application epoch — shows it arrived. Dropping it here meant one
     // lost Finished left us "connected" and the peer waiting for good.
-    if (!isServer && ctx.selectedVersion === DTLS_VERSION.DTLS1_3 && ctx.currentFlight.length > 0) {
+    if (!isServer && ctx.selectedVersion === DTLS_VERSION.DTLS1_3 && haveFlight()) {
       ctx.finalFlightPending = true;
       startRetransmitTimer();
     } else {
+      // DTLS 1.2: if the last flight is ours — sent after the peer's last
+      // message, so nothing of the peer's acknowledges it — it is kept for
+      // the peer's retransmissions (dtls12AnswerRetransmission). No timer:
+      // RFC 6347 §4.2.4's FINISHED state answers, it does not repeat.
+      if (ctx.selectedVersion !== DTLS_VERSION.DTLS1_3 && !ctx.newFlightPending && haveFlight()) {
+        ctx.lastFlight12 = ctx.currentFlight;
+      }
       cancelRetransmit();
       startNewFlight();
     }
@@ -1779,12 +2573,14 @@ function DTLSSession(options) {
     // only symptom is a connection that dies after a handshake that
     // looked complete, which is exactly the DTLS 1.3 interop case.
     _ldbg('ERROR ' + (e && e.message ? e.message : e) +
-          (e && e.alertDescription != null ? ' alertDesc=' + e.alertDescription : '') +
+          (e && e.alertDesc != null ? ' alertDesc=' + e.alertDesc : '') +
           (e && e.code ? ' code=' + e.code : ''));
-    ev.emit('error', e);
+    // TLSSession has sent its alert already.
+    fail(e);
   });
 
   tls.on('session', function(ticket) {
+    ctx.lastSession = ticket;
     ev.emit('session', ticket);
   });
 
@@ -1799,12 +2595,20 @@ function DTLSSession(options) {
       return;
     }
     if (typeof data === 'string') data = new TextEncoder().encode(data);
+    // One send, one record — a datagram's message is not split. Larger than
+    // a record may carry (2^14, or the peer's record_size_limit): refused,
+    // not sent as a record the peer must refuse.
+    if (data.length > tls.recordSendLimit()) {
+      let big = new RangeError('DTLS: ' + data.length + ' bytes in one record, more than ' + tls.recordSendLimit() + ' (the record limit)');
+      big.code = 'ERR_DTLS_RECORD_TOO_LARGE';
+      ev.emit('error', big);
+      return;
+    }
 
     let epoch = ctx.selectedVersion === DTLS_VERSION.DTLS1_3
-      ? (ctx.writeEpoch !== null ? ctx.writeEpoch : 3)
+      ? appEpoch()
       : 1;
-    let record = buildRecord(epoch, CT.APPLICATION_DATA, data);
-    _ldbgTx(record, 'L1383'); ev.emit('packet', record);
+    queueOut({ kind: 'raw', epoch: epoch, contentType: CT.APPLICATION_DATA, payload: data, label: 'data' });
   }
 
 
@@ -1821,23 +2625,10 @@ function DTLSSession(options) {
     // 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) {
-      // After a KeyUpdate the live epoch is 4, 5, ... — the peer has moved on
-      // and no longer reads epoch 3, so a close_notify sent there is dropped
-      // and the shutdown looks like a timeout instead of a clean close.
-      epoch = (ctx.writeEpoch !== null && ctx.keys[ctx.writeEpoch])
-        ? ctx.writeEpoch
-        : (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();
-    cancelKeyUpdateRetransmit();
+    // type instead of a clean shutdown. alertEpoch() decides, as for every
+    // alert we send.
+    sendAlertRecord(alertEpoch(), new Uint8Array([1, 0])); // warning, close_notify
+    shutDown();
     ev.emit('close');
   }
 
@@ -1944,6 +2735,15 @@ function DTLSSession(options) {
 
     /** Negotiated ALPN. */
     getALPN: function() { return tls.getALPN(); },
+    // Encrypted Client Hello, as TLSSocket's echStatus / echBackend.
+    getEchStatus: function() { return tls.getEchStatus(); },
+    isEchBackend: function() { return tls.isEchBackend(); },
+    // External PSK: the identity this connection was authenticated with.
+    getPskIdentity: function() { return tls.getPskIdentity(); },
+    /** Connection IDs (RFC 9146), once agreed: { local, peer } — local, in
+     *  the records we receive; peer, in those we send (NewConnectionId may
+     *  have changed it since the handshake). Null otherwise. */
+    getConnectionIds: getConnectionIds,
 
     /** Peer certificate. */
     getPeerCertificate: function() { return tls.getPeerCertificate(); },
@@ -1965,6 +2765,31 @@ function DTLSSession(options) {
 
     /** Whether this connection resumed an earlier session. */
     isSessionReused: function() { return !!tls.isResumed; },
+
+    /** The last session (a Buffer for `session` next time), as TLSSocket#getSession; undefined until one. */
+    getSession: function() { return ctx.lastSession; },
+
+    /**
+     * The path MTU: the largest datagram this session writes (every record
+     * is one datagram). Takes effect for the next message fragmented —
+     * a flight already sent is resent as it was cut. 128..65507 bytes.
+     */
+    setMTU: function(mtu) { ctx.mtu = checkedMtu(mtu); },
+    getMTU: function() { return ctx.mtu; },
+
+    /**
+     * Where each flight's retransmission timer starts (it doubles on every
+     * timeout, to 60 s). RFC 9147 §5.8.2 recommends 1 s; a known short
+     * path can go lower. 10..60000 ms. The flight in progress keeps its own.
+     */
+    setInitialRetransmitTimeout: function(ms) {
+      ctx.initialRetransmitTimeout = checkedRetransmitTimeout(ms);
+      // Said explicitly: the schedule from now on — every flight's timer
+      // starts there, whatever round trip is measured (currentRto).
+      ctx.fixedRto = true;
+      ctx.srtt = null; ctx.rttvar = null;
+      if (ctx.retransmitTimer === null) ctx.retransmitTimeout = ctx.initialRetransmitTimeout;
+    },
   };
 
   for (let k in api) {
@@ -1980,4 +2805,5 @@ function DTLSSession(options) {
   return this;
 }
 
-export default DTLSSession;
+export default DTLSSession;
+export { SERVER_CID_LEN };