tunnelfetch 1.2.0 → 1.4.0

package/src/tls/aead.js

@@ -21,6 +21,7 @@
 import { TlsError, TlsUnsupportedError, codes, hex16 } from '../errors.js';
 import { concat, u8, u16 } from '../util/bytes.js';
 import {
+  CIPHER,
   CIPHER_PARAMS, CIPHER_NAME, MAX_PLAINTEXT, LEGACY_VERSION, TLS12, TLS13,
 } from './constants.js';
 
@@ -88,6 +89,12 @@ function seq64(seq) {
  * @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.
  */
 
 /**
@@ -97,7 +104,7 @@ function seq64(seq) {
  * @param {AeadOptions} opts
  * @returns {Promise<Aead>}
  */
-export async function createAead({ version = TLS13, cipher, key, iv }) {
+export async function createAead({ version = TLS13, cipher, key, iv, impl = null }) {
   const params = CIPHER_PARAMS[cipher];
   if (!params || params.hash === undefined) {
     throw new TlsUnsupportedError(codes.TLS_CIPHER_UNSUPPORTED,
@@ -119,8 +126,43 @@ export async function createAead({ version = TLS13, cipher, key, iv }) {
       `iv is ${iv.byteLength} bytes; ${CIPHER_NAME[cipher]} needs ${wantIv} for this version`,
       { cipher, version });
   }
-  const gcmKey = await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false,
-    ['encrypt', 'decrypt']);
+  // ChaCha20-Poly1305 has no WebCrypto on this runtime — feature-detected on workerd, where the
+  // only native path is node:crypto and taking it would cost the package its "web platform only"
+  // property. So the implementation is INJECTED: `impl` supplies seal/open, and without one the
+  // suite is never offered, so a ChaCha20 record can only be reached by a server negotiating a
+  // suite that was not in the offer, which negotiateCipher already refuses.
+  const isChaCha = cipher === CIPHER.TLS_CHACHA20_POLY1305_SHA256;
+  if (isChaCha && (typeof impl?.seal !== 'function' || typeof impl?.open !== 'function')) {
+    throw new TlsError(
+      codes.CONFIG_INVALID,
+      'ChaCha20-Poly1305 was negotiated but no implementation was supplied; pass one as ' +
+        '`ciphers: { chacha20: impl }` with seal(key, nonce, plaintext, aad) and open(...)',
+      { cipher },
+    );
+  }
+  const gcmKey = isChaCha
+    ? null
+    : await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+  const chachaKey = isChaCha ? key.slice() : null;
+  /** One seal, whichever cipher was negotiated. Returns ciphertext||tag. */
+  const seal = async (nonce, aad, plain) =>
+    isChaCha
+      ? impl.seal(chachaKey, nonce, plain, aad)
+      : new Uint8Array(
+          await crypto.subtle.encrypt(
+            { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
+            gcmKey, plain));
+  /** One open. Returns null on authentication failure, which every caller turns into tagFailure. */
+  const open = async (nonce, aad, ct) => {
+    if (isChaCha) return impl.open(chachaKey, nonce, ct, aad);
+    try {
+      return new Uint8Array(
+        await crypto.subtle.decrypt(
+          { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 }, gcmKey, ct));
+    } catch {
+      return null;
+    }
+  };
   const staticIv = iv.slice(); // defensive copy: the caller may zero or reuse its buffer
 
   const tagFailure = () => new TlsError(codes.TLS_RECORD,
@@ -152,10 +194,7 @@ export async function createAead({ version = TLS13, cipher, key, iv }) {
         inner[plaintext.byteLength] = type;
         const aad = concat([u8(23), u16(LEGACY_VERSION), u16(inner.byteLength + tagLen)]);
         const nonce = buildNonce(staticIv, seq);
-        const ct = await crypto.subtle.encrypt(
-          { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
-          gcmKey, inner);
-        return new Uint8Array(ct);
+        return await seal(nonce, aad, inner);
       },
 
       /**
@@ -177,12 +216,11 @@ export async function createAead({ version = TLS13, cipher, key, iv }) {
         const nonce = buildNonce(staticIv, seq);
         let inner;
         try {
-          inner = new Uint8Array(await crypto.subtle.decrypt(
-            { name: 'AES-GCM', iv: nonce, additionalData: header, tagLength: tagLen * 8 },
-            gcmKey, body));
+          inner = await open(nonce, header, body);
         } catch {
           throw tagFailure();
         }
+        if (inner == null) throw tagFailure();
         // Strip the zero padding to expose the real content type (RFC 8446 s5.4). Scanning
         // from the end is not constant time, but padding length is not secret from an attacker
         // who can measure it anyway via record timing; the RFC imposes no such requirement.
@@ -222,9 +260,7 @@ export async function createAead({ version = TLS13, cipher, key, iv }) {
       const explicit = seq64(seq);
       const nonce = concat([staticIv, explicit]);
       const aad = concat([explicit, u8(type), u16(TLS12), u16(plaintext.byteLength)]);
-      const ct = new Uint8Array(await crypto.subtle.encrypt(
-        { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
-        gcmKey, plaintext));
+      const ct = await seal(nonce, aad, plaintext);
       return concat([explicit, ct]);
     },
 
@@ -251,12 +287,11 @@ export async function createAead({ version = TLS13, cipher, key, iv }) {
       const aad = concat([seq64(seq), header.subarray(0, 3), u16(ptLen)]);
       let plaintext;
       try {
-        plaintext = new Uint8Array(await crypto.subtle.decrypt(
-          { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
-          gcmKey, body.subarray(8)));
+        plaintext = await open(nonce, aad, body.subarray(8));
       } catch {
         throw tagFailure();
       }
+      if (plaintext == null) throw tagFailure();
       return { type: header[0], plaintext };
     },
   };

package/src/tls/connect.js

@@ -30,13 +30,16 @@ import { RecordLayer } from './record.js';
 import { Transcript } from './transcript.js';
 import {
   ALPN_HTTP11,
+  CIPHER,
   CIPHER_PARAMS,
+  GROUP,
   HANDSHAKE_TYPE,
   SUPPORTED_GROUPS,
   TLS12,
   TLS12_CIPHERS,
   TLS13,
   TLS13_CIPHERS,
+  TLS13_CIPHERS_WITH_CHACHA,
 } from './constants.js';
 import {
   buildClientHello,
@@ -136,7 +139,12 @@ function expectServerHello(msg, offers12) {
  *   supported group; a HelloRetryRequest recovers any other choice at the cost of a round trip.
  * @property {number[]} [ciphers] cipher suites to offer, in preference order.
  * @property {number[]} [sigSchemes] signature_algorithms to offer, in preference order.
- * @property {number[]} [extensionOrder] ClientHello extension types, in the order to emit them.
+ * @property {boolean | number} [grease] send GREASE (RFC 8701) reserved values in the cipher list,
+ *   the extension list (one at each end), supported_groups, supported_versions and key_share.
+ *   Default false, because curl does not GREASE — Chromium does. A number is a seed, which makes
+ *   the hello reproducible; `true` draws one from `deps.randomBytes`. A server that negotiates a
+ *   GREASE value is refused with a typed error naming it.
+ * @property {number[] | 'shuffle'} [extensionOrder] ClientHello extension types, in the order to emit them.
  *   JA3 and JA4 hash the extension list in WIRE ORDER, so this is most of what a fingerprinter
  *   reads. Defaults to curl's order (`CURL_EXTENSION_ORDER`). Extensions not named keep their
  *   natural position at the end; `pre_shared_key` is always last whatever is asked, because RFC
@@ -190,11 +198,19 @@ function expectServerHello(msg, offers12) {
  */
 
 /**
- * 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
  */
 
 /**
@@ -249,6 +265,9 @@ export async function connectTls({ transport, hostname, verifyPeer, options = {}
   const record = new RecordLayer(transport, {
     maxHandshakeMessage: options.maxHandshakeMessage,
     maxKeyUpdates: options.maxKeyUpdates,
+    // ChaCha20-Poly1305 has no WebCrypto path here; its seal/open are injected via deps.aead and
+    // threaded to every createAead. Null for the AES-GCM-only default, which needs nothing.
+    aeadImpls: deps.aead ?? null,
   });
   // Until the ServerHello picks, the record layer speaks the LOWEST version offered. The two
   // semantics that differ before any ServerHello are alert tolerance and CCS handling, and the
@@ -277,15 +296,36 @@ async function drive({ record, hostname, verifyPeer, options, deps, versions })
   const offers13 = versions.includes(TLS13);
   const offers12 = versions.includes(TLS12);
   const alpn = options.alpn ?? [ALPN_HTTP11];
-  const groups = options.groups ?? SUPPORTED_GROUPS;
-  const offerGroups = options.offerGroups ?? DEFAULT_OFFER_GROUPS;
+
+  // The two capability-gated primitives. A ClientHello is an offer a server may take, so neither
+  // the ChaCha20 suite nor the X25519MLKEM768 group may appear on the wire unless an implementation
+  // was injected — this runtime can perform neither on its own. Both are filtered out of ANY offer
+  // list (explicit or default) when their implementation is absent, which is what makes them
+  // impossible to advertise dishonestly.
+  const chacha = deps.aead?.chacha20;
+  const mlkem = deps.kem?.x25519mlkem768;
+
+  // supported_groups, and the groups a real key_share is sent for. With ML-KEM injected the
+  // default matches curl: X25519MLKEM768 first in both, alongside x25519. Without it, the classical
+  // default is unchanged and the hybrid group is stripped from any explicit list.
+  let groups = options.groups ?? (mlkem ? [GROUP.x25519mlkem768, ...SUPPORTED_GROUPS] : SUPPORTED_GROUPS);
+  let offerGroups =
+    options.offerGroups ?? (mlkem ? [GROUP.x25519mlkem768, SUPPORTED_GROUPS[0]] : DEFAULT_OFFER_GROUPS);
+  if (!mlkem) {
+    groups = groups.filter((g) => g !== GROUP.x25519mlkem768);
+    offerGroups = offerGroups.filter((g) => g !== GROUP.x25519mlkem768);
+  }
+
   // Suites for every offered version, 1.3 first. negotiateCipher later re-checks the family of
   // the server's pick against the negotiated version, so a union offer cannot be abused to run
-  // a 1.3 suite under 1.2 or the reverse.
-  const ciphers = options.ciphers ?? [
-    ...(offers13 ? TLS13_CIPHERS : []),
+  // a 1.3 suite under 1.2 or the reverse. With ChaCha20 injected the DEFAULT switches to curl's
+  // captured TLS 1.3 order (AES-256-GCM, ChaCha20, AES-128-GCM); an explicit list keeps its own
+  // order and simply has 0x1303 filtered out when no implementation is present.
+  let ciphers = options.ciphers ?? [
+    ...(offers13 ? (chacha ? TLS13_CIPHERS_WITH_CHACHA : TLS13_CIPHERS) : []),
     ...(offers12 ? TLS12_CIPHERS : []),
   ];
+  if (!chacha) ciphers = ciphers.filter((c) => c !== CIPHER.TLS_CHACHA20_POLY1305_SHA256);
 
   // --- resumption offer ----------------------------------------------------------------------
   // Everything about the offered PSK that later steps need is derived once, up front: the Early
@@ -334,6 +374,7 @@ async function drive({ record, hostname, verifyPeer, options, deps, versions })
     versions,
     extensionOrder: options.extensionOrder,
     sigSchemes: options.sigSchemes,
+    grease: options.grease ?? false,
     random: options.clientRandom,
     legacySessionId: options.legacySessionId,
     psk: pskOffer && {

package/src/tls/constants.js

@@ -81,7 +81,7 @@ export const CIPHER = {
   // TLS 1.3
   TLS_AES_128_GCM_SHA256: 0x1301,
   TLS_AES_256_GCM_SHA384: 0x1302,
-  TLS_CHACHA20_POLY1305_SHA256: 0x1303, // named for diagnostics only; never offered
+  TLS_CHACHA20_POLY1305_SHA256: 0x1303, // offered only when an implementation is injected
   // TLS 1.2, ECDHE + AEAD only
   TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: 0xc02b,
   TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: 0xc02f,
@@ -93,13 +93,39 @@ export const CIPHER = {
 export const CIPHER_NAME = Object.fromEntries(Object.entries(CIPHER).map(([k, v]) => [v, k]));
 
 /** Offered in ClientHello, in preference order. */
-export const TLS13_CIPHERS = [CIPHER.TLS_AES_128_GCM_SHA256, CIPHER.TLS_AES_256_GCM_SHA384];
+// curl's order, captured off the wire: `0x1302 0x1303 0x1301`, AES-256 before AES-128. Everything
+// through 1.3.0 offered the reverse — the extension order and the header order were matched to curl
+// and the CIPHER order was never checked, though JA3 hashes it just as directly.
+//
+// Client preference is advisory: most servers impose their own, so what this mainly changes is the
+// fingerprint. Where a server does follow the client it now picks AES-256, which on this runtime
+// costs a little more CPU per byte than AES-128 and is what curl asks for.
+export const TLS13_CIPHERS = [CIPHER.TLS_AES_256_GCM_SHA384, CIPHER.TLS_AES_128_GCM_SHA256];
+
+/**
+ * curl 8.21.0 / OpenSSL 3.6.3 offers its TLS 1.3 suites in this exact order — AES-256-GCM,
+ * ChaCha20-Poly1305, AES-128-GCM — captured off the wire 2026-08-01 (`0x1302 0x1303 0x1301`).
+ * ChaCha20 is SECOND, right after AES-256-GCM; that is "curl's position" for it.
+ *
+ * TLS13_CIPHERS above leads with AES-128, which is the order this package has always offered and
+ * which the offline test server keys its default suite selection off; reordering it would change
+ * the negotiated suite across the whole suite. So this curl-faithful order is used ONLY when a
+ * ChaCha20 implementation has been injected — i.e. when the caller has opted into being able to
+ * perform every suite curl offers — and never otherwise. See connect.js.
+ */
+export const TLS13_CIPHERS_WITH_CHACHA = [
+  CIPHER.TLS_AES_256_GCM_SHA384,
+  CIPHER.TLS_CHACHA20_POLY1305_SHA256,
+  CIPHER.TLS_AES_128_GCM_SHA256,
+];
 
+// Likewise curl's relative order among the four suites this package implements: of its full list,
+// `0xc02c 0xc030 ... 0xc02b 0xc02f` — ECDSA before RSA within each strength, AES-256 before AES-128.
 export const TLS12_CIPHERS = [
-  CIPHER.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
-  CIPHER.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
   CIPHER.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
   CIPHER.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+  CIPHER.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
+  CIPHER.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
 ];
 
 /**
@@ -118,6 +144,14 @@ export const TLS12_CIPHERS = [
 export const CIPHER_PARAMS = {
   [CIPHER.TLS_AES_128_GCM_SHA256]: { hash: 'SHA-256', hashLen: 32, keyLen: 16, ivLen: 12, tagLen: 16 },
   [CIPHER.TLS_AES_256_GCM_SHA384]: { hash: 'SHA-384', hashLen: 48, keyLen: 32, ivLen: 12, tagLen: 16 },
+  // Parameters only. Deliberately NOT in TLS13_CIPHERS, so it is never offered unless a caller
+  // supplies an implementation — this runtime has no WebCrypto ChaCha20, and its only native path
+  // is node:crypto, which the package will not require. Having the parameters here lets the AEAD
+  // layer refuse with "no implementation supplied" rather than "unknown suite", which is the
+  // difference between a fixable configuration and an apparent dead end.
+  [CIPHER.TLS_CHACHA20_POLY1305_SHA256]: {
+    hash: 'SHA-256', hashLen: 32, keyLen: 32, ivLen: 12, tagLen: 16,
+  },
   [CIPHER.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256]: {
     hash: 'SHA-256', hashLen: 32, keyLen: 16, ivLen: 12, tagLen: 16, fixedIvLen: 4, sig: 'ecdsa',
   },
@@ -141,6 +175,11 @@ export const GROUP = {
   x25519: 0x001d,
   x448: 0x001e,
   ffdhe2048: 0x0100,
+  // Post-quantum hybrid (draft-kwiatkowski-tls-ecdhe-mlkem): ML-KEM-768 + X25519. Reachable only
+  // when an ML-KEM implementation is injected — its key exchange is not a WebCrypto primitive on
+  // this runtime — so like ChaCha20 it is never offered unless the capability was supplied. The
+  // combiner lives in hybrid.js; GROUP_PARAMS below records only the wire sizes, not an algorithm.
+  x25519mlkem768: 0x11ec,
 };
 
 export const GROUP_NAME = Object.fromEntries(Object.entries(GROUP).map(([k, v]) => [v, k]));
@@ -154,10 +193,14 @@ export const SUPPORTED_GROUPS = [GROUP.x25519, GROUP.secp256r1, GROUP.secp384r1,
 
 /**
  * WebCrypto parameters per group, discriminated on `kind` because X25519 sizes its shared
- * secret in bytes while ECDH sizes it in bits.
+ * secret in bytes while ECDH sizes it in bits, and the ML-KEM hybrid is not a WebCrypto
+ * primitive at all — it carries wire sizes only, and hybrid.js owns the crypto.
  * @typedef {{ kind: 'x25519', algorithm: { name: string }, publicLen: number, secretLen: number }
  *   | { kind: 'ec', algorithm: { name: string, namedCurve: string }, publicLen: number,
- *       secretBits: number }} GroupParams
+ *       secretBits: number }
+ *   | { kind: 'hybrid', clientShareLen: number, serverShareLen: number, secretLen: number,
+ *       mlkemPublicLen: number, mlkemSecretKeyLen: number, mlkemCiphertextLen: number,
+ *       classicalPublicLen: number, classicalSecretLen: number }} GroupParams
  */
 
 /**
@@ -175,6 +218,17 @@ export const GROUP_PARAMS = {
   [GROUP.secp521r1]: {
     kind: 'ec', algorithm: { name: 'ECDH', namedCurve: 'P-521' }, publicLen: 133, secretBits: 528,
   },
+  // X25519MLKEM768 (draft-kwiatkowski-tls-ecdhe-mlkem). The wire sizes below are FIPS 203
+  // ML-KEM-768 (ek 1184, ct 1088, dk 2400) alongside X25519 (32). The client's key_share is
+  // 1184 + 32 = 1216 bytes and the server's is 1088 + 32 = 1120; the shared secret fed to the
+  // key schedule is 32 + 32 = 64. Ordering (ML-KEM before X25519, in both the shares and the
+  // secret) is spelled out and enforced in hybrid.js — it is the whole subtlety of this group.
+  [GROUP.x25519mlkem768]: {
+    kind: 'hybrid',
+    clientShareLen: 1216, serverShareLen: 1120, secretLen: 64,
+    mlkemPublicLen: 1184, mlkemSecretKeyLen: 2400, mlkemCiphertextLen: 1088,
+    classicalPublicLen: 32, classicalSecretLen: 32,
+  },
 };
 
 // -------------------------------------------------------------------- signature schemes

package/src/tls/extensions.js

@@ -26,6 +26,16 @@ function ext(type, body) {
   return new Builder().u16(type).vector(2, body).build();
 }
 
+/**
+ * An extension of an arbitrary type with an arbitrary body. Exists for GREASE (RFC 8701), whose
+ * whole point is to carry a reserved type this package assigns no meaning to.
+ * @param {number} type
+ * @param {Uint8Array} body
+ */
+export function encodeRawExtension(type, body) {
+  return ext(type, body);
+}
+
 // ------------------------------------------------------------------ encoders (ClientHello)
 
 /**

package/src/tls/grease.js

@@ -0,0 +1,109 @@
+// GREASE (RFC 8701) — reserved values a client sprinkles through its ClientHello so that servers
+// and middleboxes stay tolerant of values they do not recognise. A peer MUST ignore them; one that
+// negotiates a GREASE value is broken, and this file makes that refusal explicit rather than
+// leaving it to a downstream "no parameters for this suite" check whose message would blame the
+// offer list.
+//
+// curl does not GREASE. Chromium does, and its placement was captured off the wire from this
+// machine's Chromium rather than recalled — two ClientHellos, compared:
+//
+//   ciphers            one GREASE value, FIRST
+//   extensions         one GREASE extension FIRST (empty) and one LAST (a single zero byte)
+//   supported_groups   one GREASE value, FIRST
+//   supported_versions one GREASE value, FIRST
+//   key_share          one GREASE entry FIRST, carrying a one-byte key
+//   ALPN               none
+//   signature_algorithms none
+//
+// The same capture settled something that would otherwise have been guessed wrong: Chromium
+// SHUFFLES its extension order on every connection. The two hellos shared an identical non-GREASE
+// extension set and had entirely different orders, with GREASE first and last both times and a
+// different GREASE value each time. So "match Chrome's extension order" is not a fixed list — it
+// is a shuffle. See `shuffleExtensions`.
+
+/** The sixteen reserved values (RFC 8701 s2): 0x0A0A, 0x1A1A, ... 0xFAFA. */
+export const GREASE_VALUES = Object.freeze(
+  Array.from({ length: 16 }, (_, i) => (i << 12) | 0x0a00 | (i << 4) | 0x0a),
+);
+
+/** @param {number} v @returns {boolean} */
+export function isGrease(v) {
+  return (v & 0x0f0f) === 0x0a0a && v >>> 8 === (v & 0xff);
+}
+
+/**
+ * A deterministic-from-seed source of GREASE values and shuffles.
+ *
+ * Seeded rather than ad-hoc `Math.random` for two reasons: this package forbids ambient randomness
+ * in `src/` (repo-hygiene enforces it, so that every byte on the wire is reproducible in a test),
+ * and a fingerprint that cannot be reproduced cannot be asserted byte-for-byte.
+ *
+ * @param {number} seed
+ */
+export function greaseSource(seed) {
+  let s = seed >>> 0 || 0x9e3779b9;
+  const next = () => {
+    s ^= s << 13;
+    s >>>= 0;
+    s ^= s >> 17;
+    s ^= s << 5;
+    s >>>= 0;
+    return s;
+  };
+  const used = new Set();
+  return {
+    /** A GREASE value not yet handed out in this hello, since Chromium never repeats one. */
+    take() {
+      for (let i = 0; i < 64; i++) {
+        const v = GREASE_VALUES[next() % GREASE_VALUES.length];
+        if (!used.has(v)) {
+          used.add(v);
+          return v;
+        }
+      }
+      /* c8 ignore next */
+      return GREASE_VALUES[used.size % GREASE_VALUES.length];
+    },
+    next,
+  };
+}
+
+/**
+ * Fisher-Yates over the middle of the extension list, leaving the ends alone.
+ *
+ * The first and last positions are not free: Chromium pins a GREASE extension to each, and
+ * `pre_shared_key` MUST be last of all (RFC 8446 s4.2.11 — the binder transcript is the hello
+ * truncated just before the binders, a range that only exists if nothing follows them). So the
+ * shuffle covers everything between the fixed ends and nothing else.
+ *
+ * @param {Array<Uint8Array>} parts encoded extensions, already ordered
+ * @param {{next: () => number}} rng
+ * @param {(e: Uint8Array) => number} typeOf
+ * @param {number} pskType
+ * @returns {Array<Uint8Array>}
+ */
+export function shuffleExtensions(parts, rng, typeOf, pskType) {
+  const out = [...parts];
+  // Anything pinned at either end stays put: leading GREASE, and trailing GREASE or pre_shared_key.
+  let lo = 0;
+  while (lo < out.length && isGrease(typeOf(out[lo]))) lo++;
+  let hi = out.length - 1;
+  while (hi > lo && (isGrease(typeOf(out[hi])) || typeOf(out[hi]) === pskType)) hi--;
+
+  for (let i = hi; i > lo; i--) {
+    const j = lo + (rng.next() % (i - lo + 1));
+    [out[i], out[j]] = [out[j], out[i]];
+  }
+  return out;
+}
+
+/**
+ * A GREASE key_share entry: a reserved group with a single-byte key, which is what Chromium sends.
+ * The byte is fixed rather than random — it is never used for anything, and a value that varies
+ * would only make the hello harder to assert on.
+ *
+ * @param {number} group
+ */
+export function greaseKeyShare(group) {
+  return { group, keyExchange: Uint8Array.of(0x00) };
+}

package/src/tls/handshake-messages.js

@@ -11,9 +11,13 @@
 import { TlsError, TlsUnsupportedError, CertificateError, codes, hex16 } from '../errors.js';
 import { concat, equal, timingSafeEqual, utf8 } from '../util/bytes.js';
 import { Builder, Cursor, vector, handshakeMessage } from './wire.js';
+import { greaseSource, greaseKeyShare, shuffleExtensions, isGrease } from './grease.js';
 // 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,
@@ -49,6 +53,7 @@ import {
   encodePreSharedKey,
   encodePskKeyExchangeModes,
   encodeRenegotiationInfo,
+  encodeRawExtension,
   encodeServerName,
   encodeSignatureAlgorithms,
   encodeStatusRequest,
@@ -75,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));
@@ -104,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(
@@ -230,6 +245,9 @@ export async function deriveSharedSecret(group, privateKey, peerKey) {
  * whatever the caller asks for, because RFC 8446 s4.2.11 defines the binder transcript as the hello
  * truncated just before the binders — a range that only exists if nothing follows them.
  */
+/** `extensionOrder: SHUFFLE_EXTENSIONS` reproduces what Chromium does — see grease.js. */
+export const SHUFFLE_EXTENSIONS = 'shuffle';
+
 export const CURL_EXTENSION_ORDER = Object.freeze([
   EXTENSION.renegotiation_info,
   EXTENSION.server_name,
@@ -282,8 +300,16 @@ export function buildClientHello({
   extensionOrder = CURL_EXTENSION_ORDER,
   extraExtensions = [],
   psk = null,
+  grease = false,
   randomBytes = defaultRandom,
 }) {
+  // A seed rather than ambient randomness: repo-hygiene forbids Math.random in src/ so that every
+  // byte this package puts on the wire is reproducible in a test, and a fingerprint that cannot be
+  // reproduced cannot be asserted byte-for-byte.
+  const g = grease === false || grease == null
+    ? null
+    : greaseSource(typeof grease === 'number' ? grease : ((randomBytes(4)[0] << 24) |
+        (randomBytes(4)[1] << 16) | (randomBytes(4)[2] << 8) | randomBytes(4)[3]) >>> 0);
   const clientRandom = random ?? randomBytes(32);
   if (clientRandom.byteLength !== 32) {
     throw new TlsError(codes.CONFIG_INVALID, `ClientHello.random must be 32 bytes, got ${clientRandom.byteLength}`);
@@ -302,7 +328,9 @@ export function buildClientHello({
     throw new TlsError(codes.CONFIG_INVALID, 'ClientHello would offer no cipher suites');
   }
 
+  // GREASE goes FIRST in each list, which is where Chromium puts it — captured, not recalled.
   const suiteBytes = new Builder();
+  if (g) suiteBytes.u16(g.take());
   for (const s of suites) suiteBytes.u16(s);
 
   if (psk && !offersTls13) {
@@ -318,11 +346,16 @@ export function buildClientHello({
     // Always offered, for either version: without it a server may not staple (RFC 6066 s8), and
     // a stapled OCSP response is the only revocation signal this package can consume.
     encodeStatusRequest(),
-    encodeSupportedGroups(groups),
+    encodeSupportedGroups(g ? [g.take(), ...groups] : groups),
     encodeSignatureAlgorithms(sigSchemes),
     alpn.length ? encodeAlpn(alpn) : null,
-    offersTls13 ? encodeSupportedVersions(versions) : null,
-    offersTls13 ? encodeKeyShare(keyShares.map(({ group, keyExchange }) => ({ group, keyExchange }))) : null,
+    offersTls13 ? encodeSupportedVersions(g ? [g.take(), ...versions] : versions) : null,
+    offersTls13
+      ? encodeKeyShare([
+          ...(g ? [greaseKeyShare(g.take())] : []),
+          ...keyShares.map(({ group, keyExchange }) => ({ group, keyExchange })),
+        ])
+      : null,
     offersTls13 ? encodePskKeyExchangeModes() : null,
     offersTls12 ? encodeExtendedMasterSecret() : null,
     offersTls12 ? encodeEcPointFormats() : null,
@@ -339,13 +372,36 @@ export function buildClientHello({
     if (part) offered.add((part[0] << 8) | part[1]);
   }
 
+  const typeOf = (e) => (e[0] << 8) | e[1];
+  // Order (or shuffle) the real extensions FIRST, then bracket them with GREASE. Doing it the
+  // other way round put both GREASE extensions at the end under a fixed order, because neither
+  // reserved type appears in any order list — and it put the trailing one after pre_shared_key,
+  // which RFC 8446 s4.2.11 forbids.
+  const laidReal =
+    extensionOrder === SHUFFLE_EXTENSIONS
+      ? shuffleExtensions(extensionParts.filter(Boolean), g ?? greaseSource(1), typeOf,
+          EXTENSION.pre_shared_key)
+      : orderExtensions(extensionParts, extensionOrder);
+
+  let laid = laidReal;
+  if (g) {
+    // Leading GREASE is empty, trailing carries a single zero byte — as captured from Chromium.
+    // The trailing one goes BEFORE any pre_shared_key, which must stay last of all.
+    const head = encodeRawExtension(g.take(), new Uint8Array(0));
+    const tail = encodeRawExtension(g.take(), Uint8Array.of(0));
+    const pskAt = laidReal.findIndex((e) => typeOf(e) === EXTENSION.pre_shared_key);
+    laid = pskAt === -1
+      ? [head, ...laidReal, tail]
+      : [head, ...laidReal.slice(0, pskAt), tail, ...laidReal.slice(pskAt)];
+  }
+
   const body = new Builder()
     .u16(LEGACY_VERSION)
     .push(clientRandom)
     .vector(1, sessionId)
     .vector(2, suiteBytes.build())
     .vector(1, Uint8Array.from([0])) // legacy_compression_methods: null only
-    .push(encodeExtensionBlock(orderExtensions(extensionParts, extensionOrder)))
+    .push(encodeExtensionBlock(laid))
     .build();
 
   const message = handshakeMessage(HANDSHAKE_TYPE.client_hello, body);
@@ -506,6 +562,19 @@ export function negotiateVersion(serverHello, { offeredVersions }) {
  */
 export function negotiateCipher(serverHello, { offeredCiphers, version }) {
   const suite = serverHello.cipherSuite;
+  // A GREASE value is reserved and MUST be ignored by a server (RFC 8701 s3). One that negotiates
+  // it is broken, and because we offered it the "was it offered" test below would let it through —
+  // so it is refused here, naming GREASE, rather than falling to the missing-parameters check
+  // whose message would blame this package's own offer list.
+  if (isGrease(suite)) {
+    throw new TlsUnsupportedError(
+      codes.TLS_CIPHER_UNSUPPORTED,
+      `server selected the GREASE cipher suite ${hex16(suite)}, which RFC 8701 reserves and ` +
+        'requires a server to ignore. It exists in the offer precisely to detect peers that do ' +
+        'not.',
+      { cipherSuite: suite },
+    );
+  }
   if (!offeredCiphers.includes(suite)) {
     throw new TlsUnsupportedError(
       codes.TLS_CIPHER_UNSUPPORTED,