tunnelfetch 1.3.0 → 1.4.0

package/src/tls/handshake-messages.js

@@ -15,6 +15,9 @@ import { greaseSource, greaseKeyShare, shuffleExtensions, isGrease } from './gre
 // der.js is a strict ASN.1 reader with no trust policy in it; the signature-format conversion
 // lives there so the certificate path builder and this file cannot drift apart.
 import { ecdsaDerToRaw } from '../trust/der.js';
+// The X25519MLKEM768 hybrid is a group like any other to the driver, but its key exchange is not
+// a WebCrypto primitive, so its keygen/derive live in their own module and are dispatched to here.
+import { HYBRID_GROUP, deriveHybridSecret, generateHybridKeyShare } from './hybrid.js';
 import {
   CIPHER_NAME,
   CIPHER_PARAMS,
@@ -77,16 +80,20 @@ const defaultRandom = (n) => crypto.getRandomValues(new Uint8Array(n));
 /**
  * Generate an ephemeral key share for one group.
  * `generateKeyPair` is injectable so a recorded handshake can be replayed with the exact private
- * key that produced it.
+ * key that produced it. X25519MLKEM768 dispatches to hybrid.js, using the injected ML-KEM
+ * implementation from `deps.kem`.
  *
  * @param {number} group
  * @param {import('./connect.js').TlsDeps} [deps]
  * @returns {Promise<KeyShare>}
  */
-export async function generateKeyShare(group, { generateKeyPair } = {}) {
+export async function generateKeyShare(group, deps = {}) {
+  if (group === HYBRID_GROUP) {
+    return generateHybridKeyShare(deps.kem?.x25519mlkem768, deps);
+  }
   const params = requireSupportedGroup(group, 'ClientHello');
   const gen =
-    generateKeyPair ??
+    deps.generateKeyPair ??
     ((algorithm) => crypto.subtle.generateKey(algorithm, false, ['deriveBits']));
   const pair = await gen(params.algorithm, group);
   const raw = new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey));
@@ -106,11 +113,17 @@ export async function generateKeyShare(group, { generateKeyPair } = {}) {
  * so it is checked here first.
  *
  * @param {number} group
- * @param {CryptoKey} privateKey our ephemeral private key for the group
+ * @param {CryptoKey | import('./hybrid.js').HybridPrivate} privateKey our ephemeral private key
+ *   for the group (a compound value for the ML-KEM hybrid)
  * @param {Uint8Array} peerKey the server's raw public key from its key_share
+ * @param {import('./connect.js').TlsDeps} [deps] carries the injected ML-KEM implementation the
+ *   hybrid group needs; unused by the classical groups
  * @returns {Promise<Uint8Array>} throws on any degenerate or malformed peer key
  */
-export async function deriveSharedSecret(group, privateKey, peerKey) {
+export async function deriveSharedSecret(group, privateKey, peerKey, deps = {}) {
+  if (group === HYBRID_GROUP) {
+    return deriveHybridSecret(deps.kem?.x25519mlkem768, privateKey, peerKey);
+  }
   const params = requireSupportedGroup(group, 'ServerHello');
   if (peerKey.byteLength !== params.publicLen) {
     throw new TlsError(

package/src/tls/handshake.js

@@ -355,7 +355,7 @@ export async function continueTls13(ctx) {
   // Only psk_dhe_ke is ever offered (s4.2.9), so a key exchange happens whether or not the PSK
   // was taken; selectServerKeyShare fails closed on a ServerHello without key_share.
   const server = selectServerKeyShare(sh, keyShares);
-  const shared = await deriveSharedSecret(server.group, server.privateKey, server.keyExchange);
+  const shared = await deriveSharedSecret(server.group, server.privateKey, server.keyExchange, deps);
 
   // s7.1: with a PSK in use the Early Secret is extracted from it; otherwise from zeros. The
   // accepted offer already carries that extraction (connect.js derived it for the binder), and

package/src/tls/hybrid.js

@@ -0,0 +1,166 @@
+// X25519MLKEM768 (group 0x11EC): the post-quantum hybrid key exchange of
+// draft-kwiatkowski-tls-ecdhe-mlkem.
+//
+// This is a HYBRID: two independent key agreements run side by side and their secrets are
+// concatenated, so the session is safe as long as EITHER holds — X25519 against a classical
+// attacker, ML-KEM-768 against a future quantum one. ML-KEM is not a WebCrypto primitive on this
+// runtime, so its keygen/encapsulate/decapsulate are INJECTED (the same discipline ChaCha20 gets
+// in aead.js): without an implementation the group is never offered, and a ClientHello is an offer
+// a server may take. The X25519 half is plain WebCrypto, exactly as x25519 alone is elsewhere.
+//
+// The three orderings below are the whole subtlety of this file, and each is a silent trap: a
+// reversed concatenation does not throw, it produces a shared secret that merely DIFFERS, so the
+// handshake fails only later, at a Finished that will not verify — indistinguishable from a server
+// bug. draft-kwiatkowski-tls-ecdhe-mlkem fixes them, and they were confirmed against a real
+// X25519MLKEM768 server (Cloudflare) by completing a handshake, not read off the page:
+//
+//   * client key_share  = ML-KEM-768 encapsulation key (1184) || X25519 public key (32)  = 1216
+//   * server key_share   = ML-KEM-768 ciphertext        (1088) || X25519 public key (32)  = 1120
+//   * shared secret      = ML-KEM-768 shared secret       (32) || X25519 shared secret (32) =  64
+//
+// ML-KEM comes FIRST in all three. (This is the opposite of the NIST-curve hybrids such as
+// SecP256r1MLKEM768, where the classical share leads — which is exactly why it must be verified
+// per group rather than assumed.) ML-KEM decapsulation uses FIPS 203 implicit rejection: a bad
+// ciphertext yields a pseudorandom secret rather than an error, so a mismatch here can ONLY show
+// up as a bad Finished, never as an exception. That is by design and is why offline agreement is
+// necessary but not sufficient — see the live test.
+
+import { TlsError, codes, hex16 } from '../errors.js';
+import { concat } from '../util/bytes.js';
+import { GROUP, GROUP_PARAMS } from './constants.js';
+
+export const HYBRID_GROUP = GROUP.x25519mlkem768;
+const P = GROUP_PARAMS[HYBRID_GROUP];
+
+const X25519_ALG = { name: 'X25519' };
+
+/**
+ * An injected ML-KEM-768 implementation (FIPS 203). Shapes match `wasmcrypto`'s `mlkem768`:
+ * @typedef {object} MlKem768
+ * @property {(seed?: Uint8Array) => { publicKey: Uint8Array, secretKey: Uint8Array }} keygen
+ *   ML-KEM.KeyGen; `publicKey` is the 1184-byte encapsulation key, `secretKey` the 2400-byte
+ *   decapsulation key.
+ * @property {(publicKey: Uint8Array) => { cipherText: Uint8Array, sharedSecret: Uint8Array }}
+ *   encapsulate ML-KEM.Encaps; used by a server, exercised by the offline test server.
+ * @property {(cipherText: Uint8Array, secretKey: Uint8Array) => Uint8Array} decapsulate
+ *   ML-KEM.Decaps; returns the 32-byte shared secret (implicit rejection on a bad ciphertext).
+ */
+
+/**
+ * The private half kept between generateHybridKeyShare and deriveHybridSecret: the ML-KEM
+ * decapsulation key and the X25519 private key. Not a CryptoKey, so callers treat KeyShare's
+ * private component opaquely (they already do — it only ever flows back into derivation).
+ * @typedef {object} HybridPrivate
+ * @property {Uint8Array} mlkemSecretKey the ML-KEM decapsulation key
+ * @property {CryptoKey} classicalPrivateKey the X25519 private key
+ */
+
+function checkLen(actual, want, what) {
+  if (actual !== want) {
+    throw new TlsError(
+      codes.TLS_HANDSHAKE,
+      `X25519MLKEM768 ${what} is ${actual} bytes, expected ${want}`,
+      { group: HYBRID_GROUP, got: actual, expected: want },
+    );
+  }
+}
+
+/**
+ * Generate a client key share for X25519MLKEM768.
+ *
+ * @param {MlKem768} kem the injected ML-KEM-768 implementation
+ * @param {import('./connect.js').TlsDeps} [deps] `generateKeyPair` is honoured for the X25519
+ *   half so a recorded handshake can be replayed with a fixed classical key
+ * @returns {Promise<{ group: number, keyExchange: Uint8Array, privateKey: HybridPrivate }>}
+ *   `keyExchange` is the 1216-byte wire share (ML-KEM encapsulation key || X25519 public key)
+ */
+export async function generateHybridKeyShare(kem, { generateKeyPair } = {}) {
+  requireKem(kem);
+  // ML-KEM keypair. The encapsulation key goes on the wire; the decapsulation key is kept.
+  const mlkem = kem.keygen();
+  checkLen(mlkem.publicKey?.byteLength, P.mlkemPublicLen, 'ML-KEM encapsulation key');
+  checkLen(mlkem.secretKey?.byteLength, P.mlkemSecretKeyLen, 'ML-KEM decapsulation key');
+
+  // X25519 keypair, via WebCrypto exactly as the standalone x25519 group does.
+  const gen =
+    generateKeyPair ??
+    ((algorithm) => crypto.subtle.generateKey(algorithm, false, ['deriveBits']));
+  const pair = await gen(X25519_ALG, GROUP.x25519);
+  const classicalPublic = new Uint8Array(await crypto.subtle.exportKey('raw', pair.publicKey));
+  checkLen(classicalPublic.byteLength, P.classicalPublicLen, 'X25519 public key');
+
+  // ML-KEM FIRST, then X25519 — the client-share ordering. 1184 + 32 = 1216.
+  const keyExchange = concat([mlkem.publicKey, classicalPublic]);
+  return {
+    group: HYBRID_GROUP,
+    keyExchange,
+    privateKey: { mlkemSecretKey: mlkem.secretKey, classicalPrivateKey: pair.privateKey },
+  };
+}
+
+/**
+ * Derive the 64-byte hybrid shared secret from the server's X25519MLKEM768 key share.
+ *
+ * @param {MlKem768} kem the injected ML-KEM-768 implementation
+ * @param {HybridPrivate} privateKey what generateHybridKeyShare kept
+ * @param {Uint8Array} serverShare the server's 1120-byte key_exchange (ciphertext || X25519 pub)
+ * @returns {Promise<Uint8Array>} ML-KEM shared secret (32) || X25519 shared secret (32) = 64
+ */
+export async function deriveHybridSecret(kem, privateKey, serverShare) {
+  requireKem(kem);
+  if (!privateKey || !privateKey.mlkemSecretKey || !privateKey.classicalPrivateKey) {
+    throw new TlsError(codes.CONFIG_INVALID,
+      'X25519MLKEM768 derivation needs the ML-KEM decapsulation key and the X25519 private key');
+  }
+  // The server share is ML-KEM ciphertext (1088) then X25519 public key (32). A wrong length here
+  // is the server contradicting the group it selected; fail closed rather than slice past the end.
+  checkLen(serverShare.byteLength, P.serverShareLen, 'server key_share');
+  const ciphertext = serverShare.subarray(0, P.mlkemCiphertextLen);
+  const classicalPublic = serverShare.subarray(P.mlkemCiphertextLen);
+
+  // ML-KEM decapsulation. Implicit rejection (FIPS 203) means a tampered ciphertext yields a
+  // pseudorandom secret, not an error — the mismatch can only surface at Finished, by design.
+  const mlkemSecret = kem.decapsulate(ciphertext, privateKey.mlkemSecretKey);
+  checkLen(mlkemSecret?.byteLength, P.classicalSecretLen, 'ML-KEM shared secret');
+
+  // X25519 agreement, with the same small-order guard the standalone x25519 path applies.
+  let classicalPeer;
+  try {
+    classicalPeer = await crypto.subtle.importKey('raw', classicalPublic, X25519_ALG, false, []);
+  } catch (cause) {
+    throw new TlsError(codes.TLS_HANDSHAKE,
+      `X25519MLKEM768 server X25519 share is not a valid public key: ${cause?.message}`,
+      { group: HYBRID_GROUP });
+  }
+  let classicalSecret;
+  try {
+    classicalSecret = new Uint8Array(
+      await crypto.subtle.deriveBits({ ...X25519_ALG, public: classicalPeer },
+        privateKey.classicalPrivateKey, P.classicalSecretLen * 8));
+  } catch (cause) {
+    throw new TlsError(codes.TLS_HANDSHAKE,
+      `X25519MLKEM768 X25519 agreement failed: ${cause?.message ?? cause}. This usually means a ` +
+        'degenerate or small-order server key.', { group: HYBRID_GROUP });
+  }
+  // RFC 7748 s6.1: an all-zero X25519 output is a small-order peer key. Reject, as x25519 does.
+  if (classicalSecret.every((b) => b === 0)) {
+    throw new TlsError(codes.TLS_HANDSHAKE,
+      'X25519MLKEM768 X25519 shared secret is all zeroes, indicating a small-order server key');
+  }
+
+  // ML-KEM FIRST, then X25519 — the shared-secret ordering. 32 + 32 = 64.
+  return concat([mlkemSecret, classicalSecret]);
+}
+
+/** @param {MlKem768} kem */
+function requireKem(kem) {
+  if (typeof kem?.keygen !== 'function' || typeof kem?.decapsulate !== 'function') {
+    throw new TlsError(
+      codes.CONFIG_INVALID,
+      `${hex16(HYBRID_GROUP)} (x25519mlkem768) was reached but no ML-KEM-768 implementation was ` +
+        'supplied; pass one as `groups: { x25519mlkem768: impl }` with keygen()/encapsulate()/' +
+        'decapsulate()',
+      { group: HYBRID_GROUP },
+    );
+  }
+}

package/src/tls/record.js

@@ -20,7 +20,7 @@ import {
 import { TlsError, TlsUnsupportedError, codes, hex8, hex16 } from '../errors.js';
 import {
   RECORD_TYPE, HANDSHAKE_TYPE, ALERT_DESC, ALERT_LEVEL, MAX_PLAINTEXT, MAX_CIPHERTEXT,
-  LEGACY_VERSION, TLS12, TLS13, CIPHER_PARAMS,
+  LEGACY_VERSION, TLS12, TLS13, CIPHER, CIPHER_PARAMS,
 } from './constants.js';
 import { createAead } from './aead.js';
 import { trafficKeys, nextTrafficSecret } from './keyschedule.js';
@@ -106,6 +106,10 @@ async function withGrace(promise, ms) {
  *   record, TLS 1.3 only
  * @property {null | ((msg: HandshakeMessage) => void | Promise<void>)} [onPostHandshake]
  *   NewSessionTicket consumer; default is to discard
+ * @property {null | { chacha20?: import('./aead.js').AeadOptions['impl'] }} [aeadImpls] injected
+ *   AEAD implementations by name. ChaCha20-Poly1305 has no WebCrypto path on this runtime, so its
+ *   seal/open are supplied here and threaded into every createAead for the ChaCha20 suite (initial
+ *   keys and each KeyUpdate rotation). Absent for the AES-GCM-only default, which needs nothing.
  */
 
 export class RecordLayer {
@@ -122,6 +126,9 @@ export class RecordLayer {
     this._shutdownGraceMs = opts.shutdownGraceMs ?? 2000;
     this._padding = opts.padding ?? null;
     this._onPostHandshake = opts.onPostHandshake ?? null;
+    // Injected AEAD implementations (ChaCha20-Poly1305). Threaded into every createAead so a
+    // KeyUpdate rotation reaches for the same implementation the initial keys used.
+    this._aeadImpls = opts.aeadImpls ?? null;
 
     this._version = TLS13; // semantics selector; setVersion() pins it when negotiated
     /** @type {DirectionState} */
@@ -250,10 +257,22 @@ export class RecordLayer {
     } else if (!key || !iv) {
       throw new TlsError(codes.CONFIG_INVALID, 'keys need either a traffic secret or key+iv');
     }
-    const aead = await createAead({ version: this._version, cipher, key, iv });
+    const aead = await createAead({
+      version: this._version, cipher, key, iv, impl: this._implFor(cipher),
+    });
     return { aead, seq: 0n, cipher, hash: params.hash, secret: secret ?? null };
   }
 
+  /**
+   * The injected AEAD implementation a suite needs, or null. Only ChaCha20-Poly1305 needs one on
+   * this runtime; every AES-GCM suite goes through WebCrypto and passes null.
+   * @param {number} cipher
+   * @returns {import('./aead.js').AeadOptions['impl'] | null}
+   */
+  _implFor(cipher) {
+    return cipher === CIPHER.TLS_CHACHA20_POLY1305_SHA256 ? (this._aeadImpls?.chacha20 ?? null) : null;
+  }
+
   // ------------------------------------------------------------------ read side
 
   /**
@@ -840,7 +859,9 @@ export class RecordLayer {
     const secret = await nextTrafficSecret(s.hash, s.secret);
     const params = CIPHER_PARAMS[s.cipher];
     const { key, iv } = await trafficKeys(params.hash, secret, params.keyLen, params.ivLen);
-    const aead = await createAead({ version: this._version, cipher: s.cipher, key, iv });
+    const aead = await createAead({
+      version: this._version, cipher: s.cipher, key, iv, impl: this._implFor(s.cipher),
+    });
     this._send = { aead, seq: 0n, cipher: s.cipher, hash: s.hash, secret };
   }
 

package/src/warmup-fixture.js

@@ -18,61 +18,62 @@ export const WARMUP_HOSTNAME = "warmup.invalid";
 export const WARMUP_NOW = 1893456000000; // fixed epoch ms inside the chain's validity window
 
 const CLIENT_PRIV =
-  "MC4CAQAwBQYDK2VuBCIEINivgNQO5n8jwnzWfEWjdR14q7Km+UhPnqyL3RtkDbF7";
+  "MC4CAQAwBQYDK2VuBCIEIGD2kIBgmWlTqN+qzpUvC5PMClhKiudEWslvOrbnG7lq";
 const CLIENT_PUB =
-  "o5wNrq9yxfTLf8U3jLhUsXB52Kmf2q3zodyy/4jELSM=";
+  "c4dk24oOgG+LLBpm0e90sFXS+UhcTLZpEIrCDhTPgCo=";
 const CLIENT_RANDOM =
   "AwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dw=";
 const SESSION_ID =
   "BRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1o=";
 const CLIENT_HELLO =
-  "AQAA9AMDAwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dwgBRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1oADBMB" +
-  "EwLAK8AvwCzAMAEAAJ//AQABAAAAABMAEQAADndhcm11cC5pbnZhbGlkAAUABQEAAAAAAAsAAgEAAAoACgAIAB0AFwAYABkAEAAL" +
-  "AAkIaHR0cC8xLjEAFwAAAA0AFgAUBAMFAwYDCAQIBQgGCAcEAQUBBgEAKwAFBAMEAwMALQACAQEAMwAmACQAHQAgo5wNrq9yxfTL" +
-  "f8U3jLhUsXB52Kmf2q3zodyy/4jELSM=";
+  "AQAA9AMDAwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dwgBRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1oADBMC" +
+  "EwHALMAwwCvALwEAAJ//AQABAAAAABMAEQAADndhcm11cC5pbnZhbGlkAAUABQEAAAAAAAsAAgEAAAoACgAIAB0AFwAYABkAEAAL" +
+  "AAkIaHR0cC8xLjEAFwAAAA0AFgAUBAMFAwYDCAQIBQgGCAcEAQUBBgEAKwAFBAMEAwMALQACAQEAMwAmACQAHQAgc4dk24oOgG+L" +
+  "LBpm0e90sFXS+UhcTLZpEIrCDhTPgCo=";
 const SERVER_BYTES =
-  "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";
+  "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" +
+  "kAgj5tcHEb0GRYv7RQ==";
 const ROOT_DER =
   "MIIC2jCCAcKgAwIBAgIBATANBgkqhkiG9w0BAQsFADAeMRwwGgYDVQQDDBNXYXJtdXAgRml4dHVyZSBSb290MB4XDTI1MDEwMTAw" +
   "MDAwMFoXDTM1MDEwMTAwMDAwMFowHjEcMBoGA1UEAwwTV2FybXVwIEZpeHR1cmUgUm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEP" +
-  "ADCCAQoCggEBAMEAjrxVUntvHweCVz7mjYZTWZiTOW3mabXocCrFXKs8CcJVYNGQkpvhC/1VIr4t7hdrSPG31j6PvR4x0OAZTJZR" +
-  "k++Zo1jPUWIG3YomFJWhVjoJqoZTcO8uMDydvO75OTxto6Mc5gpfzHgfc52aAqemSqnfzryjupS6o1KOwbE1byLjM/Mmpp4CrRXx" +
-  "Fy/Jd8g2w1dSTTZo7QDIYBuZcNW4UYna9Mpac7otnv8JdlRSKonbbxXbx1E2GUm0tVM+4B5ARtBOFggnZYNW+KvQwcl4NRLTrFZS" +
-  "KNaRAW78DxclmSBsMm0lV+lsnV9miyuR2vfsj1FwSHKe1gzf12yRMpECAwEAAaMjMCEwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8B" +
-  "Af8EBAMCAgQwDQYJKoZIhvcNAQELBQADggEBAGmB1ws+kKHGtO5D8UnCCyXI/q5LtHsMDO+lDwp/6HAKJ6xVnJCNVP4d1/nTwMVm" +
-  "KeJTfEseakqaVSiUcowlPEgSM1OVIRU6aRqBog4cjyBt9F74cmdy+VOewkd4jwHUDnkuj8sNx6BdU8FN83w2nIlQ35g/exzQDP8q" +
-  "mB/GtQlnGbmi6mRMKzFn5stSwQS5tcTwz8h5dkDG2FtsBG4f8YDs8r2G0ur7FQD9aIhlttcUUdSE1mZHm4itgqgyE+hreL0x0wqz" +
-  "7V7NQK7fMH8OLTr5JrjVMyrpX8EQqyntEkAS8IaaQ42h3GNo1+HRVeJ9M53noaveacxhtTZDnI5u8wA=";
+  "ADCCAQoCggEBAIRQ0+WIza3mrmr2wDgG0u3kvBYYFp23u+AcofQDWrUKZj/6uOOq2Ur2rZF3cSSkjedqouNvtFfKTA8kUD4IHaM/" +
+  "rDjUNBI7ITsyRHieixi39qddXpTgb9+WInm0pyIvAgCLZlyg33AG7y29mEfPTJYAcWaSYRLQwu+/dMAshxC16i3zSU5HleZntE9F" +
+  "VJbYR5QGIS6Y5MzU+1hSlXxSbl5boQXTJql1OdWt4t8MU/7voXJhZ6mdGXXiPQXdSrc8txKUJLqd6UgP5AnIhbWhHkfg0MpAXm0Y" +
+  "5rrodnclqTNI5ibDDt+ylA9vk5AiCH+mCqPtNd7mERMsP2rpBvRM/EsCAwEAAaMjMCEwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8B" +
+  "Af8EBAMCAgQwDQYJKoZIhvcNAQELBQADggEBAHjQ1bWdwKNQpAefj7nyNX7KHdvfNK7TRpAobtunyuEQE6Ia4d1CIOGNHAX87UM2" +
+  "4otia7hM4S2oysqvW+HWpMR4cCe2TDofg/nvWo9SOJCsKRcn5caeB3AL0LG7eh97tDoMiytI1xQ2RN/ZajxQ8Fc9WdUjIosiOc5l" +
+  "IQFg6pBvzsAhwC2hFuspk31ay/mwE6t5pP+68ZJELqwjBiN6M+vGjIoQ/29tMsgnOaPCXB5vp4gaZpaisu1QiZEG95O7owrJ49+u" +
+  "h6JTXWf2j7qxiPqdvqYUGjqZSwKRwZGMYWwIRub/tSdRaRiBpV7QXjarJ8IK9yTAOwe/2fHAX5VbOI0=";
 
 export const WARMUP_FIXTURE = {
   clientPrivPkcs8: () => B(CLIENT_PRIV),

package/types/client.d.ts

@@ -64,6 +64,15 @@ export function install(options?: ClientOptions): () => void;
  *   yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
  *   the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
  *   matching a browser's Accept-Encoding, not saving CPU.
+ * @property {{ chacha20?: import('./tls/aead.js').AeadOptions['impl'] }} [ciphers] injected AEAD
+ *   implementations, by capability name. `chacha20` (seal/open, RFC 8439) is what lets
+ *   TLS_CHACHA20_POLY1305_SHA256 be offered and performed — WebCrypto has no ChaCha20 on this
+ *   runtime, and a suite offered but not performable is a dead connection if a server selects it,
+ *   so without this the suite stays out of the ClientHello. Required by `profiles.chrome`.
+ * @property {{ x25519mlkem768?: import('./tls/hybrid.js').MlKem768 }} [groups] injected key-exchange
+ *   implementations, by capability name. `x25519mlkem768` (ML-KEM-768 keygen/encapsulate/
+ *   decapsulate) is what lets the post-quantum hybrid group be offered and performed; without it
+ *   the group stays out of the ClientHello. Required by `profiles.chrome`.
  * @property {boolean} [keepAlive] default true.
  * @property {import('./profiles.js').FingerprintProfile} [profile] one coherent network identity
  *   instead of a dozen knobs that can disagree — TLS, HTTP/2, header order and default headers
@@ -237,6 +246,25 @@ export type ClientOptions = {
      * matching a browser's Accept-Encoding, not saving CPU.
      */
     decoders?: Record<string, import("./client/decode.js").BodyDecoder> | undefined;
+    /**
+     * injected AEAD
+     * implementations, by capability name. `chacha20` (seal/open, RFC 8439) is what lets
+     * TLS_CHACHA20_POLY1305_SHA256 be offered and performed — WebCrypto has no ChaCha20 on this
+     * runtime, and a suite offered but not performable is a dead connection if a server selects it,
+     * so without this the suite stays out of the ClientHello. Required by `profiles.chrome`.
+     */
+    ciphers?: {
+        chacha20?: import("./tls/aead.js").AeadOptions["impl"];
+    } | undefined;
+    /**
+     * injected key-exchange
+     * implementations, by capability name. `x25519mlkem768` (ML-KEM-768 keygen/encapsulate/
+     * decapsulate) is what lets the post-quantum hybrid group be offered and performed; without it
+     * the group stays out of the ClientHello. Required by `profiles.chrome`.
+     */
+    groups?: {
+        x25519mlkem768?: import("./tls/hybrid.js").MlKem768;
+    } | undefined;
     /**
      * default true.
      */

package/types/profile/chrome.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `profiles.chrome` with the two capabilities this package cannot perform natively already wired
+ * in. Everything else about it — the cipher list, the groups, the shuffled extension order, GREASE,
+ * the HTTP/2 SETTINGS and pseudo-header order, the request header order — comes from the
+ * declaration unchanged, and all of it was captured off the wire from Chrome 150.
+ *
+ * @type {import('../profiles.js').FingerprintProfile & {
+ *   ciphers: Record<string, unknown>, groups: Record<string, unknown> }}
+ */
+export const chrome: import("../profiles.js").FingerprintProfile & {
+    ciphers: Record<string, unknown>;
+    groups: Record<string, unknown>;
+};
+import { chacha20poly1305 } from './vendor/chacha20poly1305.js';
+import { mlkem768 } from './vendor/mlkem768.js';
+export { chacha20poly1305, mlkem768 };

package/types/profile/vendor/chacha20poly1305.d.ts

@@ -0,0 +1,7 @@
+export const buildId: "ec15f83a678a";
+export namespace chacha20poly1305 {
+    /** seal(key32, nonce12, plaintext, aad?) -> ciphertext||tag (RFC 8439 AEAD) */
+    function seal(key: any, nonce: any, plaintext: any, aad?: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+    /** open(key32, nonce12, ciphertextAndTag, aad?) -> plaintext; throws on auth failure */
+    function open(key: any, nonce: any, ciphertext: any, aad?: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+}

package/types/profile/vendor/mlkem768.d.ts

@@ -0,0 +1,23 @@
+export const buildId: "e17c38843d1e";
+export namespace mlkem768 {
+    export { PK_B as publicKeyBytes };
+    export { SK_B as secretKeyBytes };
+    export { CT_B as cipherTextBytes };
+    export let sharedSecretBytes: number;
+    /** keygen(seed?) — seed is d||z (64 bytes) for ML-KEM.KeyGen_internal; omitted = fresh CSPRNG */
+    export function keygen(seed: any): {
+        publicKey: Uint8Array<ArrayBuffer>;
+        secretKey: Uint8Array<ArrayBuffer>;
+    };
+    /** encapsulate(publicKey, msg?) — msg is m (32 bytes) for ML-KEM.Encaps_internal */
+    export function encapsulate(publicKey: any, msg: any): {
+        cipherText: Uint8Array<ArrayBuffer>;
+        sharedSecret: Uint8Array<ArrayBuffer>;
+    };
+    /** decapsulate(cipherText, secretKey) -> sharedSecret (implicit rejection per FIPS 203) */
+    export function decapsulate(cipherText: any, secretKey: any): Uint8Array<ArrayBuffer>;
+}
+declare const PK_B: any;
+declare const SK_B: any;
+declare const CT_B: any;
+export {};

package/types/profiles.d.ts

@@ -59,17 +59,21 @@ export const curl: Readonly<{
  * `applyProfile` refuses both cases with a message naming what is missing.
  */
 export const chrome: Readonly<{
-    name: "chromium (TLS layer only)";
+    name: "chrome/150";
     tls: Readonly<{
         ciphers: readonly number[];
         groups: readonly number[];
+        offerGroups: readonly number[];
         sigSchemes: readonly number[];
         alpn: string[];
         extensionOrder: "shuffle";
         grease: true;
     }>;
+    http2Settings: readonly number[][];
+    http2ConnectionWindow: number;
+    http2PseudoHeaderOrder: readonly string[];
+    headerOrder: readonly string[];
     headers: readonly string[][];
-    http2Settings: null;
     requires: readonly string[];
 }>;
 /** @type {Record<string, FingerprintProfile>} */

package/types/tls/aead.d.ts

@@ -25,6 +25,12 @@ export function buildNonce(iv: Uint8Array, seq: number | bigint): Uint8Array;
  * @property {Uint8Array} key
  * @property {Uint8Array} iv the 12-byte static IV for TLS 1.3, the 4-byte implicit salt for
  *   TLS 1.2
+ * @property {{seal: (k: Uint8Array, n: Uint8Array, p: Uint8Array, aad: Uint8Array) => Uint8Array,
+ *             open: (k: Uint8Array, n: Uint8Array, c: Uint8Array, aad: Uint8Array) => Uint8Array | null}}
+ *   [impl] caller-supplied AEAD, required for ChaCha20-Poly1305 and unused otherwise. This runtime
+ *   has no WebCrypto ChaCha20 — its only native path is node:crypto, and taking it would cost the
+ *   package its "web platform only" property — so the implementation is injected. `open` returns
+ *   null when authentication fails.
  */
 /**
  * Create record protection for one direction under one key. A new key (handshake -> application,
@@ -33,7 +39,7 @@ export function buildNonce(iv: Uint8Array, seq: number | bigint): Uint8Array;
  * @param {AeadOptions} opts
  * @returns {Promise<Aead>}
  */
-export function createAead({ version, cipher, key, iv }: AeadOptions): Promise<Aead>;
+export function createAead({ version, cipher, key, iv, impl }: AeadOptions): Promise<Aead>;
 /**
  * Record protection for one direction under one key. `encrypt` returns the encrypted record
  * body ready for framing; `decrypt` either returns authenticated plaintext (with the inner
@@ -64,4 +70,14 @@ export type AeadOptions = {
      * TLS 1.2
      */
     iv: Uint8Array;
+    /**
+     * caller-supplied AEAD, required for ChaCha20-Poly1305 and unused otherwise. This runtime
+     * has no WebCrypto ChaCha20 — its only native path is node:crypto, and taking it would cost the
+     * package its "web platform only" property — so the implementation is injected. `open` returns
+     * null when authentication fails.
+     */
+    impl?: {
+        seal: (k: Uint8Array, n: Uint8Array, p: Uint8Array, aad: Uint8Array) => Uint8Array;
+        open: (k: Uint8Array, n: Uint8Array, c: Uint8Array, aad: Uint8Array) => Uint8Array | null;
+    } | undefined;
 };

package/types/tls/connect.d.ts

@@ -71,11 +71,19 @@
  * @property {object} peer
  */
 /**
- * Injectable nondeterminism. Supplying these makes a handshake byte-for-byte reproducible, which
- * is what allows a recorded session to be replayed in an offline test.
+ * Injectable nondeterminism and crypto primitives the platform does not provide.
+ *
+ * `randomBytes` and `generateKeyPair` supply reproducibility (a recorded session replayed in an
+ * offline test). `aead` and `kem` supply capabilities this runtime lacks entirely: ChaCha20 and
+ * ML-KEM are absent from WebCrypto here, so an implementation must be injected before the suite or
+ * group they back can be offered — a ClientHello being an offer a server may take.
  * @typedef {object} TlsDeps
  * @property {(n: number) => Uint8Array} [randomBytes]
  * @property {(algorithm: object, group: number) => Promise<CryptoKeyPair>} [generateKeyPair]
+ * @property {{ chacha20?: import('./aead.js').AeadOptions['impl'] }} [aead] injected AEAD
+ *   implementations by name; `chacha20` gates and performs TLS_CHACHA20_POLY1305_SHA256
+ * @property {{ x25519mlkem768?: import('./hybrid.js').MlKem768 }} [kem] injected KEM
+ *   implementations by name; `x25519mlkem768` gates and performs the X25519MLKEM768 hybrid group
  */
 /**
  * What a completed handshake reports about itself.
@@ -256,12 +264,30 @@ export type CapturedTicket = {
     peer: object;
 };
 /**
- * Injectable nondeterminism. Supplying these makes a handshake byte-for-byte reproducible, which
- * is what allows a recorded session to be replayed in an offline test.
+ * Injectable nondeterminism and crypto primitives the platform does not provide.
+ *
+ * `randomBytes` and `generateKeyPair` supply reproducibility (a recorded session replayed in an
+ * offline test). `aead` and `kem` supply capabilities this runtime lacks entirely: ChaCha20 and
+ * ML-KEM are absent from WebCrypto here, so an implementation must be injected before the suite or
+ * group they back can be offered — a ClientHello being an offer a server may take.
  */
 export type TlsDeps = {
     randomBytes?: ((n: number) => Uint8Array) | undefined;
     generateKeyPair?: ((algorithm: object, group: number) => Promise<CryptoKeyPair>) | undefined;
+    /**
+     * injected AEAD
+     * implementations by name; `chacha20` gates and performs TLS_CHACHA20_POLY1305_SHA256
+     */
+    aead?: {
+        chacha20?: import("./aead.js").AeadOptions["impl"];
+    } | undefined;
+    /**
+     * injected KEM
+     * implementations by name; `x25519mlkem768` gates and performs the X25519MLKEM768 hybrid group
+     */
+    kem?: {
+        x25519mlkem768?: import("./hybrid.js").MlKem768;
+    } | undefined;
 };
 /**
  * What a completed handshake reports about itself.