lemon-tls 0.6.0 → 0.9.0

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 = [];

package/src/session/cert_compression.js

@@ -0,0 +1,157 @@
+/**
+ * TLS Certificate Compression (RFC 8879), TLS 1.3 and DTLS 1.3.
+ *
+ * A certificate chain is most of what a server sends in its handshake —
+ * 3-5 KB for a public CA's chain, against a few hundred bytes for the rest.
+ * Compressed it is often half that or less: the certificates repeat names,
+ * extensions and OIDs. Over QUIC it decides how many round trips the
+ * handshake takes: before the client's address is validated a server may
+ * send three times what it received (RFC 9000 §8.1), ~3.6 KB for a 1200-byte
+ * Initial, and a chain that does not fit waits a round trip for the
+ * client's next packet. Browsers offer it (Chrome: brotli; Firefox: zlib,
+ * brotli, zstd).
+ *
+ * The client lists the algorithms it can decompress (compress_certificate,
+ * extension 27); the server, holding one it can compress with, sends
+ * CompressedCertificate (handshake type 25) in place of Certificate. The
+ * same works the other way for a client certificate, when the server's
+ * CertificateRequest carries the extension.
+ */
+
+import zlib from 'node:zlib';
+import crypto from 'node:crypto';
+
+function brotliOptions(b) {
+  return { params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11, [zlib.constants.BROTLI_PARAM_SIZE_HINT]: b.length } };
+}
+
+// RFC 8879 §3, and the IANA registry: zlib 1, brotli 2, zstd 3.
+const ALGORITHMS = {
+  1: { name: 'zlib',
+       compress: (b) => zlib.deflateSync(b, { level: 9 }),
+       compressAsync: (b, cb) => zlib.deflate(b, { level: 9 }, cb),
+       decompress: (b, max) => zlib.inflateSync(b, { maxOutputLength: max }) },
+  2: { name: 'brotli',
+       compress: (b) => zlib.brotliCompressSync(b, brotliOptions(b)),
+       compressAsync: (b, cb) => zlib.brotliCompress(b, brotliOptions(b), cb),
+       decompress: (b, max) => zlib.brotliDecompressSync(b, { maxOutputLength: max }) },
+};
+// zstd where node:zlib has it (Node 22.15+, 23.8+).
+if (typeof zlib.zstdCompressSync === 'function' && typeof zlib.zstdDecompressSync === 'function') {
+  ALGORITHMS[3] = { name: 'zstd',
+    compress: (b) => zlib.zstdCompressSync(b),
+    compressAsync: (b, cb) => zlib.zstdCompress(b, cb),
+    decompress: (b, max) => zlib.zstdDecompressSync(b, { maxOutputLength: max }) };
+}
+
+const BY_NAME = {};
+for (const code in ALGORITHMS) BY_NAME[ALGORITHMS[code].name] = Number(code);
+
+/** The algorithms this build can use, in its preference (best ratio first). */
+function supported_cert_compression() {
+  return [2, 3, 1].filter((c) => !!ALGORITHMS[c]);
+}
+
+/**
+ * An option naming algorithms — ['brotli', 'zlib'], codes, or true (all) /
+ * false (none) — as codes this build supports. Throws on a name it does not
+ * know; one it knows but cannot run here (zstd on an older Node) is left out.
+ */
+function parse_cert_compression(value, what) {
+  if (value === undefined || value === null) return null;
+  if (value === false) return [];
+  if (value === true) return supported_cert_compression();
+  if (!Array.isArray(value)) throw new TypeError((what || 'certificateCompression') + ' must be an array of algorithms (brotli, zlib, zstd), true or false');
+  const out = [];
+  for (const v of value) {
+    let code = typeof v === 'number' ? v : BY_NAME[String(v).toLowerCase()];
+    if (code === undefined && String(v).toLowerCase() === 'zstd') continue;   // not in this Node
+    if (code === undefined || (code !== 1 && code !== 2 && code !== 3)) throw new TypeError((what || 'certificateCompression') + ': unknown algorithm ' + JSON.stringify(v));
+    if (ALGORITHMS[code] && out.indexOf(code) < 0) out.push(code);
+  }
+  return out;
+}
+
+// A chain is compressed once per algorithm: the server sends the same bytes
+// on every handshake, and brotli at quality 11 is not cheap. Keyed by a hash
+// of the uncompressed message; bounded.
+const cache = new Map();
+const CACHE_MAX = 64;
+
+function cache_key(body, alg) {
+  return alg + ':' + crypto.createHash('sha256').update(body).digest('hex');
+}
+function cache_put(key, out) {
+  cache.set(key, out);
+  if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
+}
+
+/** `body` (an encoded Certificate message body) compressed with `alg`. */
+function compress_certificate_body(body, alg) {
+  const a = ALGORITHMS[alg];
+  if (!a) return null;
+  const key = cache_key(body, alg);
+  let out = cache.get(key);
+  if (out) return out;
+  out = new Uint8Array(a.compress(Buffer.from(body)));
+  cache_put(key, out);
+  return out;
+}
+
+// The same, ahead of the first handshake and off the event loop (zlib's
+// thread pool): what that handshake would have done synchronously — brotli
+// at quality 11 is 4 ms for a 400-byte chain and 18 ms for a 9 KB one, the
+// first time a server sends it, while that client waits — is in the cache
+// when it comes. A chain already there, or on its way, is not done twice.
+// callback() when every algorithm's is in; a failure leaves that one to
+// the handshake, as before.
+const pending = new Map();   // key → callbacks waiting on it
+function precompress_certificate_body(body, algs, callback) {
+  let left = 1;
+  const done = () => { if (--left === 0 && callback) callback(); };
+  for (const alg of algs) {
+    const a = ALGORITHMS[alg];
+    if (!a || !a.compressAsync) continue;
+    const key = cache_key(body, alg);
+    if (cache.has(key)) continue;
+    left++;
+    if (pending.has(key)) { pending.get(key).push(done); continue; }
+    pending.set(key, [done]);
+    a.compressAsync(Buffer.from(body), (err, out) => {
+      if (!err && !cache.has(key)) cache_put(key, new Uint8Array(out));
+      const waiters = pending.get(key) || []; pending.delete(key);
+      for (const w of waiters) w();
+    });
+  }
+  done();
+}
+
+/**
+ * A CompressedCertificate's contents back to the Certificate message body,
+ * or null: an algorithm not ours, data that does not decompress, or a
+ * length other than the one declared (RFC 8879 §4: bad_certificate). Never
+ * more than the declared length is produced — nor more than `limit`.
+ */
+function decompress_certificate_body(alg, data, uncompressedLength, limit) {
+  const a = ALGORITHMS[alg];
+  if (!a) return null;
+  if (!(uncompressedLength > 0) || (limit && uncompressedLength > limit)) return null;
+  let out;
+  try { out = a.decompress(Buffer.from(data), uncompressedLength); }
+  catch (e) { return null; }
+  if (out.length !== uncompressedLength) return null;
+  return new Uint8Array(out);
+}
+
+function cert_compression_name(alg) {
+  return ALGORITHMS[alg] ? ALGORITHMS[alg].name : String(alg);
+}
+
+export {
+  supported_cert_compression,
+  parse_cert_compression,
+  compress_certificate_body,
+  precompress_certificate_body,
+  decompress_certificate_body,
+  cert_compression_name,
+};

package/src/session/ecdh.js

@@ -1,6 +1,6 @@
 /**
  * ECDH key generation and shared secret helpers using node:crypto.
- * Supports X25519 and P-256 (secp256r1).
+ * X25519, P-256 and P-384; ML-KEM alone and in hybrids with them (below).
  */
 
 import * as crypto from 'crypto';
@@ -106,16 +106,153 @@ const NAMED_GROUP = {
   X25519:    0x001d,
   SECP256R1: 0x0017,
   SECP384R1: 0x0018,
+  // Post-quantum. KEMs, not Diffie-Hellman: the server does not make a key
+  // pair of its own, it ENCAPSULATES to the client's — see kem_server_exchange.
+  //   Hybrids (draft-ietf-tls-ecdhe-mlkem): ML-KEM (FIPS 203) and an ECDH
+  //   group together, safe if either one holds. X25519MLKEM768 is what Chrome,
+  //   Firefox, Safari and Cloudflare negotiate; the two NIST-curve hybrids are
+  //   for deployments that must use approved curves.
+  X25519MLKEM768:     0x11ec,
+  SECP256R1MLKEM768:  0x11eb,
+  SECP384R1MLKEM1024: 0x11ed,
+  //   ML-KEM alone (draft-ietf-tls-mlkem): no classical half. MLKEM1024 is
+  //   CNSA 2.0's key exchange.
+  MLKEM512:  0x0200,
+  MLKEM768:  0x0201,
+  MLKEM1024: 0x0202,
 };
 
-const SUPPORTED_GROUPS = [
-  NAMED_GROUP.X25519,     // preferred: fastest, no point validation pitfalls
+// Each group's name — the IANA registry's, as OpenSSL and node:tls spell them.
+const GROUP_NAMES = {
+  0x001d: 'X25519', 0x0017: 'P-256', 0x0018: 'P-384',
+  0x11ec: 'X25519MLKEM768', 0x11eb: 'SecP256r1MLKEM768', 0x11ed: 'SecP384r1MLKEM1024',
+  0x0200: 'MLKEM512', 0x0201: 'MLKEM768', 0x0202: 'MLKEM1024',
+};
+function group_name(group) { return GROUP_NAMES[group] || null; }
+
+// ML-KEM's three parameter sets (FIPS 203 Table 3): encapsulation key and
+// ciphertext sizes. The shared secret is 32 bytes for each.
+const MLKEM = {
+  512:  { type: 'ml-kem-512',  ek: 800,  ct: 768 },
+  768:  { type: 'ml-kem-768',  ek: 1184, ct: 1088 },
+  1024: { type: 'ml-kem-1024', ek: 1568, ct: 1568 },
+};
+
+// The classical halves of the hybrids: a share's size, a key pair, a secret.
+const ECDH_PART = {
+  x25519: { len: 32,
+            generate: function () { let priv = new Uint8Array(crypto.randomBytes(32)); return { private_key: priv, public_key: x25519_get_public_key(priv) }; },
+            shared: function (priv, pub) { return x25519_get_shared_secret(priv, pub); } },
+  p256:   { len: 65, generate: function () { return p256_generate_keypair(); },
+            shared: function (priv, pub) { check_point(pub, 65); return p256_get_shared_secret(priv, pub); } },
+  p384:   { len: 97, generate: function () { return p384_generate_keypair(); },
+            shared: function (priv, pub) { check_point(pub, 97); return p384_get_shared_secret(priv, pub); } },
+};
+function check_point(pub, len) {
+  if (pub.length !== len || pub[0] !== 0x04) throw new Error('the ECDH part must be a ' + len + '-byte uncompressed point');
+}
+
+// The KEM groups: which ML-KEM, which ECDH half (none for ML-KEM alone), and
+// which comes first — in X25519MLKEM768 the ML-KEM part leads, in both shares
+// and in the shared secret (the draft's one exception, kept for the Kyber
+// deployments); in the two NIST-curve hybrids the ECDH part leads.
+const KEM_GROUPS = {
+  0x11ec: { kem: 768,  ecdh: 'x25519', kemFirst: true },
+  0x11eb: { kem: 768,  ecdh: 'p256',   kemFirst: false },
+  0x11ed: { kem: 1024, ecdh: 'p384',   kemFirst: false },
+  0x0200: { kem: 512 },
+  0x0201: { kem: 768 },
+  0x0202: { kem: 1024 },
+};
+
+// ML-KEM comes from node:crypto (crypto.encapsulate / decapsulate) and from
+// nothing else: Node 24.7+ on OpenSSL 3.5, and Electron once its Node has the
+// BoringSSL wiring (Node 24.18+). A parameter set node:crypto lacks makes its
+// groups simply not implemented — not offered, not accepted.
+//
+// Decided once per parameter set, by a real round trip rather than by the
+// functions existing (on BoringSSL, crypto.encapsulate can be defined and
+// still not know ML-KEM) — and the raw key's SPKI wrapping taken from the key
+// made: a fixed DER prefix, as for X25519 above.
+const MLKEM_SPKI_PREFIX = {};
+function probe_mlkem(bits) {
+  if (typeof crypto.encapsulate !== 'function' || typeof crypto.decapsulate !== 'function') return false;
+  try {
+    let p = MLKEM[bits];
+    let kp = crypto.generateKeyPairSync(p.type);
+    let enc = crypto.encapsulate(kp.publicKey);
+    let dec = crypto.decapsulate(kp.privateKey, enc.ciphertext);
+    if (enc.ciphertext.length !== p.ct || Buffer.compare(Buffer.from(enc.sharedKey), Buffer.from(dec)) !== 0) return false;
+    let spki = kp.publicKey.export({ format: 'der', type: 'spki' });
+    MLKEM_SPKI_PREFIX[bits] = Buffer.from(spki.subarray(0, spki.length - p.ek));
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+const MLKEM_SETS = { 512: probe_mlkem(512), 768: probe_mlkem(768), 1024: probe_mlkem(1024) };
+const MLKEM_AVAILABLE = MLKEM_SETS[768];
+
+// Import checks the key (FIPS 203 §7.2: every coefficient below q) and throws
+// on a bad one — before any secret exists.
+function mlkem_public_key(bits, raw) {
+  return crypto.createPublicKey({ key: Buffer.concat([MLKEM_SPKI_PREFIX[bits], Buffer.from(raw)]), format: 'der', type: 'spki' });
+}
+
+function kem_group_available(group) {
+  let d = KEM_GROUPS[group];
+  return !!(d && MLKEM_SETS[d.kem]);
+}
+// The sizes of a KEM group's shares: the client's (encapsulation key and
+// ECDH public key) and the server's (ciphertext and ECDH public key).
+function kem_sizes(group) {
+  let d = KEM_GROUPS[group], m = MLKEM[d.kem], e = d.ecdh ? ECDH_PART[d.ecdh].len : 0;
+  return { client: m.ek + e, server: m.ct + e, ek: m.ek, ct: m.ct, ecdh: e };
+}
+
+// A client's default offer: the hybrid post-quantum group first where
+// node:crypto has ML-KEM, then the classical groups — what node:tls offers by
+// default (OpenSSL 3.5: X25519MLKEM768 and X25519 shares) and Chrome and
+// Firefox do. With the hybrid first, an X25519 share goes beside it
+// (tls_session), so a classical server costs no extra round trip. The cost:
+// a ClientHello of ~1.4 KB rather than ~0.3 (two QUIC Initial packets), and
+// key generation of ~0.1 ms — node:crypto's, native. Without ML-KEM (Node
+// before 24.7), the classical groups alone, X25519 first. The other
+// post-quantum groups are there to ask for (ecdhCurve), not offered unasked:
+// each is another 1–1.7 KB in every ClientHello.
+const SUPPORTED_GROUPS = (MLKEM_AVAILABLE ? [NAMED_GROUP.X25519MLKEM768] : []).concat([
+  NAMED_GROUP.X25519,     // preferred classical: fastest, no point validation pitfalls
   NAMED_GROUP.SECP256R1,
   NAMED_GROUP.SECP384R1,
-];
+]);
+
+// A server's default preference: every post-quantum group node:crypto can do,
+// first — the hybrids (X25519MLKEM768 first: what browsers send), then
+// ML-KEM alone, strongest first — then the classical ones. A client that
+// offers any post-quantum group gets one (tls_session: its first, by its own
+// order, with a HelloRetryRequest when it sent no share for it); any other
+// client gets the classical group it asked for.
+const SERVER_DEFAULT_GROUPS = [
+  NAMED_GROUP.X25519MLKEM768, NAMED_GROUP.SECP256R1MLKEM768, NAMED_GROUP.SECP384R1MLKEM1024,
+  NAMED_GROUP.MLKEM1024, NAMED_GROUP.MLKEM768, NAMED_GROUP.MLKEM512,
+].filter(kem_group_available).concat([
+  NAMED_GROUP.X25519,
+  NAMED_GROUP.SECP256R1,
+  NAMED_GROUP.SECP384R1,
+]);
+
+// Everything implemented here, on either side. A KEM group only where
+// node:crypto has its ML-KEM — a list that names it anyway (a hardcoded server
+// list, a client's options.groups) has it skipped, as with any unimplemented
+// group.
+const IMPLEMENTED_GROUPS = SERVER_DEFAULT_GROUPS;
 
 function is_supported_group(group) {
-  return SUPPORTED_GROUPS.indexOf(group) >= 0;
+  return IMPLEMENTED_GROUPS.indexOf(group) >= 0;
+}
+
+function is_kem_group(group) {
+  return !!KEM_GROUPS[group];
 }
 
 /**
@@ -123,15 +260,72 @@ function is_supported_group(group) {
  * Returns { private_key, public_key } or null for an unsupported group.
  */
 function generate_keypair(group) {
-  if (group === NAMED_GROUP.X25519) {
-    let priv = new Uint8Array(crypto.randomBytes(32));
-    return { private_key: priv, public_key: x25519_get_public_key(priv) };
-  }
+  if (group === NAMED_GROUP.X25519) return ECDH_PART.x25519.generate();
   if (group === NAMED_GROUP.SECP256R1) return p256_generate_keypair();
   if (group === NAMED_GROUP.SECP384R1) return p384_generate_keypair();
+  if (kem_group_available(group)) {
+    // The CLIENT side: an ML-KEM key pair, and an ECDH one for a hybrid; the
+    // share is the two public keys in the group's order.
+    let d = KEM_GROUPS[group], sz = kem_sizes(group);
+    let kem = crypto.generateKeyPairSync(MLKEM[d.kem].type);
+    let spki = kem.publicKey.export({ format: 'der', type: 'spki' });
+    let ek = spki.subarray(spki.length - sz.ek);
+    let ec = d.ecdh ? ECDH_PART[d.ecdh].generate() : null;
+    let pub = new Uint8Array(sz.client);
+    if (!ec) pub.set(ek, 0);
+    else if (d.kemFirst) { pub.set(ek, 0); pub.set(ec.public_key, sz.ek); }
+    else { pub.set(ec.public_key, 0); pub.set(ek, sz.ecdh); }
+    return { private_key: { kem: kem.privateKey, ecdh: ec ? ec.private_key : null }, public_key: pub };
+  }
   return null;
 }
 
+// The two halves of a share or a ciphertext, by the group's layout.
+function split_share(group, buf, kemLen) {
+  let d = KEM_GROUPS[group];
+  if (!d.ecdh) return { kem: buf, ecdh: null };
+  let e = ECDH_PART[d.ecdh].len;
+  return d.kemFirst ? { kem: buf.subarray(0, kemLen), ecdh: buf.subarray(kemLen) }
+                    : { ecdh: buf.subarray(0, e), kem: buf.subarray(e) };
+}
+// The shared secret: ML-KEM's and the ECDH one, concatenated in the group's
+// order (draft-ietf-tls-ecdhe-mlkem §3); ML-KEM alone, its own.
+function join_secret(group, kemSecret, ecdhSecret) {
+  let d = KEM_GROUPS[group];
+  if (!d.ecdh) return new Uint8Array(kemSecret);
+  let out = new Uint8Array(kemSecret.length + ecdhSecret.length);
+  if (d.kemFirst) { out.set(kemSecret, 0); out.set(ecdhSecret, kemSecret.length); }
+  else { out.set(ecdhSecret, 0); out.set(kemSecret, ecdhSecret.length); }
+  return out;
+}
+
+/**
+ * The SERVER side of a KEM group: from the client's key share, the server's
+ * key share and the shared secret, together. There is no server key pair to
+ * make first — the ciphertext IS the server's share (with, for a hybrid, the
+ * server's ECDH public key).
+ * Throws on a malformed share; the caller turns that into illegal_parameter.
+ */
+function kem_server_exchange(group, clientShare) {
+  if (!kem_group_available(group)) throw new Error('not an implemented KEM group: 0x' + (group >>> 0).toString(16));
+  let d = KEM_GROUPS[group], sz = kem_sizes(group);
+  if (!clientShare || clientShare.length !== sz.client) {
+    throw new Error(group_name(group) + ' client key_exchange must be ' + sz.client + ' bytes, got ' + (clientShare ? clientShare.length : 0));
+  }
+  let parts = split_share(group, clientShare, sz.ek);
+  let enc = crypto.encapsulate(mlkem_public_key(d.kem, parts.kem));
+  let ec = null, ecdhSecret = null;
+  if (d.ecdh) {
+    ec = ECDH_PART[d.ecdh].generate();
+    ecdhSecret = ECDH_PART[d.ecdh].shared(ec.private_key, parts.ecdh);   // throws on a bad point / all-zero X25519
+  }
+  let share = new Uint8Array(sz.server);
+  if (!ec) share.set(enc.ciphertext, 0);
+  else if (d.kemFirst) { share.set(enc.ciphertext, 0); share.set(ec.public_key, sz.ct); }
+  else { share.set(ec.public_key, 0); share.set(enc.ciphertext, sz.ecdh); }
+  return { public_key: share, shared_secret: join_secret(group, new Uint8Array(enc.sharedKey), ecdhSecret) };
+}
+
 /**
  * Validate a peer's key_exchange value for `group` and normalize it to the
  * form the primitives below expect.
@@ -144,6 +338,19 @@ function generate_keypair(group) {
 function normalize_peer_public_key(group, pub) {
   if (!pub || pub.length === 0) throw new Error('empty key_exchange');
 
+  if (is_kem_group(group)) {
+    // A client's share (encapsulation key, and the ECDH part of a hybrid) or
+    // a server's (ciphertext, and the ECDH part) — nothing else. The ML-KEM
+    // key's own validity is checked by encapsulate; the ECDH part by its
+    // primitive.
+    if (!kem_group_available(group)) throw new Error('unsupported group 0x' + (group >>> 0).toString(16));
+    let sz = kem_sizes(group);
+    if (pub.length !== sz.client && pub.length !== sz.server) {
+      throw new Error(group_name(group) + ' key_exchange must be ' + sz.client + ' or ' + sz.server + ' bytes, got ' + pub.length);
+    }
+    return pub;
+  }
+
   if (group === NAMED_GROUP.X25519) {
     if (pub.length !== 32) {
       throw new Error('X25519 key_exchange must be 32 bytes, got ' + pub.length);
@@ -204,14 +411,34 @@ function get_shared_secret(group, localPrivateRaw, remotePublicRaw) {
   if (group === NAMED_GROUP.X25519)    return x25519_get_shared_secret(localPrivateRaw, pub);
   if (group === NAMED_GROUP.SECP256R1) return p256_get_shared_secret(localPrivateRaw, pub);
   if (group === NAMED_GROUP.SECP384R1) return p384_get_shared_secret(localPrivateRaw, pub);
+  if (kem_group_available(group)) {
+    // The CLIENT side: the server's share is the ciphertext (and, for a
+    // hybrid, the server's ECDH public key), in the group's order.
+    let sz = kem_sizes(group);
+    if (pub.length !== sz.server) {
+      throw new Error(group_name(group) + ' server key_exchange must be ' + sz.server + ' bytes, got ' + pub.length);
+    }
+    let d = KEM_GROUPS[group];
+    let parts = split_share(group, pub, sz.ct);
+    let kemShared = new Uint8Array(crypto.decapsulate(localPrivateRaw.kem, parts.kem));
+    let ecdhShared = d.ecdh ? ECDH_PART[d.ecdh].shared(localPrivateRaw.ecdh, parts.ecdh) : null;
+    return join_secret(group, kemShared, ecdhShared);
+  }
 
   throw new Error('unsupported group 0x' + (group >>> 0).toString(16));
 }
 
 export {
   NAMED_GROUP,
+  GROUP_NAMES,
+  group_name,
+  kem_group_available,
   SUPPORTED_GROUPS,
+  SERVER_DEFAULT_GROUPS,
+  MLKEM_AVAILABLE,
   is_supported_group,
+  is_kem_group,
+  kem_server_exchange,
   generate_keypair,
   normalize_peer_public_key,
   get_shared_secret,
@@ -221,4 +448,4 @@ export {
   p256_get_shared_secret,
   p384_generate_keypair,
   p384_get_shared_secret
-};
+};