lemon-tls 0.7.0 → 0.9.0

package/src/dtls_session.js

@@ -67,7 +67,7 @@ import {
 } from './record.js';
 
 import { timingSafeEqualU8 } from './utils.js';
-import { SUPPORTED_GROUPS as ECDH_SUPPORTED_GROUPS } from './session/ecdh.js';
+import { SUPPORTED_GROUPS as ECDH_SUPPORTED_GROUPS, SERVER_DEFAULT_GROUPS } from './session/ecdh.js';
 import { default_signature_schemes } from './session/signing.js';
 
 
@@ -194,6 +194,11 @@ function DTLSSession(options) {
     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,
@@ -331,6 +336,21 @@ function DTLSSession(options) {
   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) {
@@ -340,16 +360,20 @@ function DTLSSession(options) {
         versions.indexOf(DTLS_VERSION.DTLS1_2) >= 0
       );
     }
-    if (!tlsSetup.local_supported_groups) {
-      tlsSetup.local_supported_groups = ECDH_SUPPORTED_GROUPS.slice(); // whatever ecdh.js implements
-    }
+    // (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
+  // Server cert/key.
+  //
+  // The whole options object goes in, not just key+cert: createSecureContext
+  // also reads passphrase, ca, ciphers, sigalgs, ecdhCurve, honorCipherOrder,
+  // 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({ key: options.key, cert: options.cert });
+    let sctx = createSecureContext(options);
     tlsSetup.local_cert_chain = sctx.certificateChain;
     tlsSetup.cert_private_key = sctx.privateKey;
   }
@@ -1020,6 +1044,20 @@ function DTLSSession(options) {
   }
 
   function processRecord(record) {
+    // A record in an epoch above 0 that did not decrypt is not the peer's
+    // (forged, corrupted, or a late packet from a previous session on the
+    // same address) — RFC 6347 §4.1.2.7 / RFC 9147 §4.5.2: discard it
+    // silently. Its content is still ciphertext: as an ALERT its second byte
+    // is random, which emitted 'error' and failed the whole connection; as
+    // APPLICATION_DATA it went up to SCTP as data.
+    if (record.epoch > 0 && !record.encrypted) return;
+    // Once connected, everything the peer sends is protected. A plaintext
+    // (epoch 0) alert or application data at that point is unauthenticated —
+    // anyone able to send a UDP packet from the peer's address could close
+    // the connection with a one-record close_notify, or inject data.
+    if (ctx.state === 'connected' && !record.encrypted &&
+        (record.type === CT.ALERT || record.type === CT.APPLICATION_DATA)) return;
+
     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
@@ -1841,6 +1879,24 @@ function DTLSSession(options) {
 
     /** Peer certificate. */
     getPeerCertificate: function() { return tls.getPeerCertificate(); },
+
+    /** TLS fingerprints (see TLSSession): JA4, JA5 of the ClientHello, JA4S
+     *  of the ServerHello. The transport character resolves to 'd' on its
+     *  own — the inner TLSSession reads the 0xFE high byte off the hello's
+     *  legacy_version — so no `protocol` override is needed for plain DTLS. */
+    getJA4: function(opts) { return tls.getJA4(opts); },
+    getJA5: function(opts) { return tls.getJA5(opts); },
+    getJA4S: function(opts) { return tls.getJA4S(opts); },
+
+    /** Set the key and certificate for this connection (Node parity). */
+    setKeyCert: function(ctxOrOpts) { return tls.setKeyCert(ctxOrOpts); },
+
+    /** Finished verify_data, ours and the peer's (RFC 5929 channel binding). */
+    getFinished: function() { return tls.getFinished(); },
+    getPeerFinished: function() { return tls.getPeerFinished(); },
+
+    /** Whether this connection resumed an earlier session. */
+    isSessionReused: function() { return !!tls.isResumed; },
   };
 
   for (let k in api) {

package/src/dtls_socket.js

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

package/src/node_options.js

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

package/src/record.js

@@ -373,10 +373,52 @@ function buildAad12(seqNum, recordType, plaintextLen) {
 }
 
 /**
- * Encrypt a TLS 1.2 GCM record fragment. Returns explicit_nonce(8) || ciphertext || tag(16).
+ * TLS 1.2 ChaCha20-Poly1305 (RFC 7905), shared by the three TLS 1.2 record
+ * functions below. Told apart from AES-GCM the way the DTLS 1.2 functions do
+ * it: by the write IV the key block gave the suite — 12 bytes for ChaCha20,
+ * a 4-byte salt for GCM. No explicit nonce on the wire; the nonce is the IV
+ * XOR the sequence number; the AAD is the same as GCM's.
+ *
+ * The TLS 1.2 functions handled GCM only. A ChaCha20 suite was negotiated —
+ * it is in the default offer, and clients without AES hardware prefer it —
+ * and then every record failed: the peer's Finished did not decrypt
+ * (bad_record_mac), and ours could not have been read either.
+ */
+function chacha12Seal(pt, key, iv12, seqNum, recordType) {
+  const cipher = crypto.createCipheriv('chacha20-poly1305', key, getChachaNonce12(iv12, seqNum), { authTagLength: 16 });
+  cipher.setAAD(buildAad12(seqNum, recordType, pt.length), { plaintextLength: pt.length });
+  const ct = cipher.update(pt);
+  cipher.final();
+  return { ct: ct, tag: cipher.getAuthTag() };
+}
+
+function chacha12Open(fragment, key, iv12, seqNum, recordType) {
+  if (fragment.length < 16) throw new Error('TLS 1.2 ChaCha20 fragment too short');
+  const ct  = fragment.subarray(0, fragment.length - 16);
+  const tag = fragment.subarray(fragment.length - 16);
+  const decipher = crypto.createDecipheriv('chacha20-poly1305', key, getChachaNonce12(iv12, seqNum), { authTagLength: 16 });
+  decipher.setAAD(buildAad12(seqNum, recordType, ct.length), { plaintextLength: ct.length });
+  decipher.setAuthTag(tag);
+  const pt = decipher.update(ct);
+  decipher.final();
+  return pt;
+}
+
+/**
+ * Encrypt a TLS 1.2 AEAD record fragment.
+ * AES-GCM (4-byte salt): explicit_nonce(8) || ciphertext || tag(16).
+ * ChaCha20-Poly1305 (12-byte IV): ciphertext || tag(16).
  * Perf: computes seq-bytes once for both explicit nonce and AAD (was computed twice).
  */
 function encrypt12(pt, key, salt4, seqNum, recordType) {
+  if (salt4.length === 12) {
+    const sealed = chacha12Seal(pt, key, salt4, seqNum, recordType);
+    const out12 = new Uint8Array(sealed.ct.length + 16);
+    out12.set(sealed.ct, 0);
+    out12.set(sealed.tag, sealed.ct.length);
+    return out12;
+  }
+
   // Shared big-endian seq encoding (used as both explicit_nonce and AAD[0..8])
   const hi = (seqNum / 0x100000000) | 0;
   const lo = seqNum >>> 0;
@@ -437,6 +479,23 @@ function encrypt12(pt, key, salt4, seqNum, recordType) {
  */
 function encryptCompleteRecord12(pt, key, salt4, seqNum, recordType, version) {
   const ptLen = pt.length;
+
+  // ChaCha20-Poly1305: header || ciphertext || tag — no explicit IV.
+  if (salt4.length === 12) {
+    const sealed = chacha12Seal(pt, key, salt4, seqNum, recordType);
+    const cBodyLen = ptLen + 16;
+    const cVer = version || 0x0303;
+    const cRec = Buffer.allocUnsafe(5 + cBodyLen);
+    cRec[0] = recordType & 0xff;
+    cRec[1] = (cVer >>> 8) & 0xff;
+    cRec[2] = cVer & 0xff;
+    cRec[3] = (cBodyLen >>> 8) & 0xff;
+    cRec[4] = cBodyLen & 0xff;
+    sealed.ct.copy(cRec, 5);
+    sealed.tag.copy(cRec, 5 + ptLen);
+    return cRec;
+  }
+
   // Record body: 8 explicit_iv + ptLen ciphertext + 16 tag
   const bodyLen = 8 + ptLen + 16;
   const ver = version || 0x0303;
@@ -493,11 +552,15 @@ function encryptCompleteRecord12(pt, key, salt4, seqNum, recordType, version) {
 }
 
 /**
- * Decrypt a TLS 1.2 GCM record fragment. Input: explicit_nonce(8) || ciphertext || tag(16).
+ * Decrypt a TLS 1.2 AEAD record fragment.
+ * AES-GCM input: explicit_nonce(8) || ciphertext || tag(16).
+ * ChaCha20-Poly1305 input: ciphertext || tag(16).
  * Perf: subarray (zero-copy views) instead of slice (copies); returns Node Buffer
  * (which IS a Uint8Array subclass) instead of re-copying to a plain Uint8Array.
  */
 function decrypt12(fragment, key, salt4, seqNum, recordType) {
+  if (salt4.length === 12) return chacha12Open(fragment, key, salt4, seqNum, recordType);
+
   if (fragment.length < 24) throw new Error('TLS 1.2 fragment too short');
 
   // Zero-copy views over the input
@@ -732,7 +795,9 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
     decipher.setAuthTag(tag);
     let pt = decipher.update(ct);
     decipher.final();
-    return new Uint8Array(pt);
+    // A view, not a copy: pt is a fresh Buffer that owns its whole
+    // ArrayBuffer and nothing else holds it. Same Uint8Array type as before.
+    return new Uint8Array(pt.buffer, pt.byteOffset, pt.byteLength);
   }
 
   // AES-GCM: strip the 8-byte explicit nonce.
@@ -748,7 +813,8 @@ function decryptDtls12(fragment, key, ivSalt, epoch, seq, type) {
   decipher.setAuthTag(tag);
   let pt = decipher.update(ct);
   decipher.final();
-  return new Uint8Array(pt);
+  // A view, not a copy — see the ChaCha branch above.
+  return new Uint8Array(pt.buffer, pt.byteOffset, pt.byteLength);
 }
 
 /** Build complete encrypted DTLS 1.2 record (header + encrypted payload). */
@@ -1102,7 +1168,8 @@ function decryptEncryptedDtls13(data, keys, fullEpoch) {
   seq = acceptedSeq;
 
   {
-    let inner = parseInnerPlaintext(new Uint8Array(pt));
+    // A view, not a copy: pt is the decipher's fresh Buffer, owned by no one else.
+    let inner = parseInnerPlaintext(new Uint8Array(pt.buffer, pt.byteOffset, pt.byteLength));
 
     // RFC 9147 §4.5.1 anti-replay: only AFTER the tag verifies do we consult
     // and update the sliding window. Checking before deprotection would let a

package/src/secure_context.js

@@ -60,17 +60,28 @@ function makeX509FromDerOrPem(buf) {
 }
 
 function makePrivateKeyFromDerOrPem(buf, passphrase) {
+  // node:crypto rejects an explicit `passphrase: null` with ERR_INVALID_ARG_VALUE
+  // — for an unencrypted key the property must be ABSENT, not present-and-null.
+  // Callers that forward an optional option straight through would otherwise
+  // break every unencrypted key, which is the overwhelmingly common case.
+  let pass = (passphrase === null || passphrase === undefined) ? undefined : passphrase;
+
   if (isPEM(buf)) {
-    return crypto.createPrivateKey({ key: buf, format: 'pem', passphrase: passphrase });
+    let opts = { key: buf, format: 'pem' };
+    if (pass !== undefined) opts.passphrase = pass;
+    return crypto.createPrivateKey(opts);
   } else {
     let der = Buffer.from(buf), keyObj = null;
     try {
-      keyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8', passphrase: passphrase });
+      keyObj = crypto.createPrivateKey(Object.assign({ key: der, format: 'der', type: 'pkcs8' },
+                                        pass !== undefined ? { passphrase: pass } : {}));
     } catch (e1) {
       try {
-        keyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs1', passphrase: passphrase });
+        keyObj = crypto.createPrivateKey(Object.assign({ key: der, format: 'der', type: 'pkcs1' },
+                                        pass !== undefined ? { passphrase: pass } : {}));
       } catch (e2) {
-        keyObj = crypto.createPrivateKey({ key: der, format: 'der', type: 'sec1', passphrase: passphrase });
+        keyObj = crypto.createPrivateKey(Object.assign({ key: der, format: 'der', type: 'sec1' },
+                                        pass !== undefined ? { passphrase: pass } : {}));
       }
     }
     return keyObj;
@@ -106,6 +117,40 @@ function dedupeDerArray(arr) {
 function createSecureContext(options) {
   if (!options) options = {};
 
+  // Several key/certificate pairs — node:tls's arrays: `key` an array of
+  // keys (or { pem, passphrase }), `cert` an array of chains, one per key —
+  // for a server that holds certificates of more than one kind: an ML-DSA one
+  // for clients that ask for post-quantum authentication, an ECDSA or RSA one
+  // for everyone else. Each key is paired with the chain whose leaf carries
+  // its public key, in whatever order they were given; the first key's pair
+  // is the default, the others `alternates`. Which one a handshake presents
+  // is the client's signature_algorithms' to decide (tls_session).
+  if (Array.isArray(options.key) && options.key.length > 1) {
+    let certs = Array.isArray(options.cert) ? options.cert : [options.cert];
+    let contexts = options.key.map(function (k, i) {
+      let keyIn = (k && typeof k === 'object' && !Buffer.isBuffer(k) && !(k instanceof Uint8Array) && k.pem) ? k.pem : k;
+      let pass = (k && typeof k === 'object' && k.passphrase != null) ? k.passphrase : options.passphrase;
+      let pub = crypto.createPublicKey(makePrivateKeyFromDerOrPem(readMaybeFile(keyIn), pass)).export({ type: 'spki', format: 'der' });
+      let cert = null;
+      for (let j = 0; j < certs.length && cert === null; j++) {
+        let raw = readMaybeFile(certs[j]);
+        let first = isPEM(raw) ? splitPEMBlocks(raw.toString('utf8')).filter(function (b) { return b.type.indexOf('CERTIFICATE') !== -1; })[0] : { der: new Uint8Array(raw) };
+        if (!first) continue;
+        let leafPub = makeX509FromDerOrPem(first.der).publicKey.export({ type: 'spki', format: 'der' });
+        if (Buffer.compare(Buffer.from(leafPub), Buffer.from(pub)) === 0) cert = certs[j];
+      }
+      if (cert === null) throw new Error('createSecureContext: no certificate in `cert` for key ' + i);
+      return createSecureContext(Object.assign({}, options, { key: keyIn, passphrase: pass, cert: cert }));
+    });
+    let primary = contexts[0];
+    primary.alternates = contexts.slice(1).map(function (c) {
+      return { certificateChain: c.certificateChain, privateKey: c.privateKey, keyObj: c.keyObj, certObjs: c.certObjs };
+    });
+    return primary;
+  }
+  if (Array.isArray(options.key)) options = Object.assign({}, options, { key: options.key[0] && options.key[0].pem ? options.key[0].pem : options.key[0] });
+  if (Array.isArray(options.cert) && options.cert.length === 1) options = Object.assign({}, options, { cert: options.cert[0] });
+
   // --- תעודות (כולל שרשרת בתוך cert אם קיימת) ---
   let certBlocksDer = [];
   let certObjs = [];