tunnelfetch 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A fetch-shaped HTTP client that can route through HTTP CONNECT / HTTPS / SOCKS5 proxies on runtimes with only raw TCP, such as Cloudflare Workers. Implements TLS in userland because the runtime cannot verify a tunnelled peer.",
   "keywords": [
     "fetch",

package/src/client/header-order.js

@@ -0,0 +1,159 @@
+// Request header order and case — the part of a fingerprint that needs no TLS inspection at all.
+//
+// The platform's `Headers` is the wrong wire representation and always was: it iterates
+// lexicographically sorted and lowercased. So a request built through it goes out as
+// `accept, accept-encoding, connection, host, referer, user-agent` whatever the caller wrote —
+// alphabetical order, with `user-agent` last, which no real client does. curl sends:
+//
+//   Host, User-Agent, Accept, Accept-Encoding, <the caller's headers, in order>,
+//   Content-Length, Content-Type
+//
+// captured off the wire from curl 8.21.0. Note where the framing headers go: last, AFTER the
+// caller's. That is why the default order below carries a `'*'` marker rather than being a plain
+// ranking — "everything else" belongs in the middle, not at the end.
+//
+// Case matters too, and only on HTTP/1.1: real clients send `Host:` and `X-Custom:`, not `host:`
+// and `x-custom:`. HTTP/2 is the opposite — RFC 9113 s8.2.1 REQUIRES lowercase field names, and a
+// server must treat an uppercase one as malformed. So this preserves the case it was given and the
+// h2 path lowercases at the last moment, which is the only place that is correct.
+
+import { HttpError, codes } from '../errors.js';
+
+/**
+ * Default request header order, from curl 8.21.0 on the wire. `'*'` is where headers not named
+ * here go, in the order they were given — which is where curl puts the caller's own.
+ */
+export const CURL_HEADER_ORDER = Object.freeze([
+  'host',
+  'user-agent',
+  'accept',
+  'accept-encoding',
+  '*',
+  // curl sends no Connection on HTTP/1.1 (keep-alive is the default and it stays silent), so
+  // there is no reference position for it. Grouped with the other connection-and-framing headers
+  // at the end, which is where curl puts the ones it does send.
+  'connection',
+  'content-length',
+  'content-type',
+]);
+
+/**
+ * An ordered, case-preserving header list.
+ *
+ * Deliberately not a `Headers` subclass and deliberately not backed by one: the whole point is to
+ * be the thing `Headers` is not. Lookup and mutation are case-insensitive, as HTTP requires;
+ * iteration returns names exactly as they were written, in the order they arrived.
+ */
+export class OrderedHeaders {
+  /** @param {Headers | Iterable<[string, string]> | Record<string, string> | null} [init] */
+  constructor(init = null) {
+    /** @type {Array<[string, string]>} name as written, value */
+    this._list = [];
+    if (init == null) return;
+    const pairs =
+      typeof (/** @type {any} */ (init)[Symbol.iterator]) === 'function'
+        ? /** @type {Iterable<[string, string]>} */ (init)
+        : Object.entries(init);
+    for (const [name, value] of pairs) this.append(name, value);
+  }
+
+  _indexOf(name) {
+    const lower = String(name).toLowerCase();
+    return this._list.findIndex(([n]) => n.toLowerCase() === lower);
+  }
+
+  has(name) {
+    return this._indexOf(name) !== -1;
+  }
+
+  /** Comma-joined when a field appears more than once, matching `Headers.get`. */
+  get(name) {
+    const lower = String(name).toLowerCase();
+    const hits = this._list.filter(([n]) => n.toLowerCase() === lower).map(([, v]) => v);
+    return hits.length ? hits.join(', ') : null;
+  }
+
+  /**
+   * Replace IN PLACE when the field is already present, so setting a value does not move a header
+   * to the end and silently reorder the request. A caller who wrote `User-Agent` first and then
+   * had it overwritten should still see it first.
+   */
+  set(name, value) {
+    const at = this._indexOf(name);
+    if (at === -1) {
+      this.append(name, value);
+      return;
+    }
+    this._list[at] = [this._list[at][0], String(value)];
+    // A repeated field collapses to the first position, as `Headers.set` collapses to one value.
+    const lower = String(name).toLowerCase();
+    this._list = this._list.filter(([n], i) => i === at || n.toLowerCase() !== lower);
+  }
+
+  append(name, value) {
+    const n = String(name);
+    if (n === '') throw new HttpError(codes.HTTP_HEADER, 'header name must not be empty', { name });
+    this._list.push([n, String(value)]);
+  }
+
+  delete(name) {
+    const lower = String(name).toLowerCase();
+    this._list = this._list.filter(([n]) => n.toLowerCase() !== lower);
+  }
+
+  /**
+   * Put the fields into `order`, which names lowercased header names and may contain `'*'` to mark
+   * where everything unnamed goes. Fields keep their relative order within each group, so a
+   * caller's own sequence survives.
+   *
+   * @param {readonly string[]} order
+   */
+  reorder(order) {
+    const star = order.indexOf('*');
+    const rank = new Map();
+    order.forEach((name, i) => {
+      if (name !== '*') rank.set(name, i);
+    });
+    // With no '*', unnamed fields go last — the same rule the TLS extension order uses.
+    const fallback = star === -1 ? order.length : star;
+    this._list = this._list
+      .map((entry, i) => ({ entry, i, r: rank.get(entry[0].toLowerCase()) ?? fallback }))
+      .sort((a, b) => a.r - b.r || a.i - b.i)
+      .map((x) => x.entry);
+  }
+
+  /** @returns {Array<[string, string]>} names as written, in order */
+  entries() {
+    return this._list.map(([n, v]) => [n, v]);
+  }
+
+  /** Lowercased names, for HTTP/2 where RFC 9113 s8.2.1 requires them. */
+  lowercased() {
+    return this._list.map(([n, v]) => [n.toLowerCase(), v]);
+  }
+
+  [Symbol.iterator]() {
+    return this.entries()[Symbol.iterator]();
+  }
+}
+
+/**
+ * Read the caller's header names in the order and case they wrote them, BEFORE anything hands them
+ * to `Request`, which is where both are lost.
+ *
+ * Recovers what is recoverable and no more: an array of pairs or a plain object still carries the
+ * caller's order, a `Headers` or a `Request` does not — those were normalised before this package
+ * ever saw them, and there is nothing here to reconstruct.
+ *
+ * @param {RequestInfo | URL} input
+ * @param {RequestInit} [init]
+ * @returns {Array<[string, string]> | null} null when the caller's order was already gone
+ */
+export function callerHeaderOrder(input, init) {
+  const raw = init?.headers ?? (input instanceof Request ? null : undefined);
+  if (raw == null) return null;
+  if (typeof Headers !== 'undefined' && raw instanceof Headers) return null;
+  if (Array.isArray(raw)) return raw.map(([n, v]) => [String(n), String(v)]);
+  if (typeof raw === 'object') return Object.entries(raw).map(([n, v]) => [n, String(v)]);
+  return null;
+}

package/src/client.js

@@ -15,6 +15,8 @@ import { ByteReader, ByteWriter, UnexpectedEofError, concat, utf8 } from './util
 import { serializeRequestHead } from './http1/request.js';
 import { bodyFraming, readResponseBody, readResponseHead } from './http1/response.js';
 import { acceptEncodingFor, decodeBody } from './client/decode.js';
+import { OrderedHeaders, CURL_HEADER_ORDER, callerHeaderOrder } from './client/header-order.js';
+import { applyProfile } from './profiles.js';
 import { CookieJar } from './client/cookies.js';
 import { DEFAULT_MAX_REDIRECTS, nextRequest, shouldRedirect } from './client/redirect.js';
 import { ConnectionPool, poolKey } from './pool.js';
@@ -82,6 +84,20 @@ const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
  *   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 {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
+ *   together. Explicit options win over it. A profile that declares capabilities this package
+ *   cannot perform is REFUSED rather than silently reduced: see `profiles.chrome`.
+ * @property {readonly string[]} [headerOrder] request header names, lowercased, in the order to
+ *   emit them; `'*'` marks where headers not named go, in the order the caller gave them. Defaults
+ *   to curl's (`CURL_HEADER_ORDER`). The platform `Headers` sorts alphabetically and lowercases, so
+ *   without this a request goes out with `user-agent` last, which no real client does.
+ * @property {string[]} [http2PseudoHeaderOrder] request pseudo-headers in the order to emit them.
+ *   Defaults to curl's. Any of the four omitted is appended rather than dropped: RFC 9113 s8.3.1
+ *   makes all four mandatory, so a request missing one is malformed rather than merely unusual.
+ * @property {Record<string, 'incremental'|'without'|'never'>} [http2HpackIndexing] per-field HPACK
+ *   indexing. Which fields enter the dynamic table is read by an Akamai-style h2 fingerprint.
+ *   Defaults to curl's: everything incremental except `:path`.
  * @property {Array<[number, number]>} [http2Settings] the HTTP/2 SETTINGS flight, as [id, value]
  *   pairs. Order is significant — an Akamai-style h2 fingerprint reads the ids in the order they
  *   are sent — so this replaces the flight rather than merging into it. Defaults to curl's. The
@@ -106,7 +122,7 @@ export class Client {
    * @param {ClientOptions} [options]
    */
   constructor(options = {}) {
-    this.options = snapshotOptions(options);
+    this.options = snapshotOptions(applyProfile(options));
     this.pool = new ConnectionPool(options.pool);
     // HTTP/2 connections are NOT pooled the way h1 is: one connection multiplexes many concurrent
     // streams, so it is not checked out per request. It lives here, keyed exactly like the h1 pool,
@@ -237,6 +253,9 @@ export function install(options = {}) {
 
 async function performFetch(client, input, init) {
   const o = client.options;
+  // Read the caller's header names and case before `Request` normalises them away: the platform
+  // `Headers` sorts lexicographically and lowercases, so by the line below both are already gone.
+  const callerOrder = callerHeaderOrder(input, init);
   const request = new Request(input, init);
   const redirectMode = init?.redirect ?? request.redirect ?? 'follow';
   const maxRedirects = o.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
@@ -251,7 +270,9 @@ async function performFetch(client, input, init) {
   let current = {
     url: new URL(request.url),
     method: request.method,
-    headers: new Headers(request.headers),
+    // The caller's own list when it survived, so its order and case reach the wire; otherwise the
+    // normalised Headers, which is all there is left to work from.
+    headers: new OrderedHeaders(callerOrder ?? request.headers),
     body,
   };
   const history = [];
@@ -446,6 +467,12 @@ function registerHttp2(client, key, conn) {
       // `tls`, and one being reachable while the other was not made "the fingerprint is
       // configurable" only half true.
       ...(client.options.http2Settings ? { settings: client.options.http2Settings } : {}),
+      ...(client.options.http2PseudoHeaderOrder
+        ? { pseudoHeaderOrder: client.options.http2PseudoHeaderOrder }
+        : {}),
+      ...(client.options.http2HpackIndexing
+        ? { hpackIndexing: client.options.http2HpackIndexing }
+        : {}),
       onClose: () => {
         client._h2conns.delete(h2);
         // Only drop the keyed entry if it is still this connection; a newer one may have replaced it.
@@ -723,11 +750,15 @@ async function sendAndReceiveH2(client, h2, current, { deadlines }) {
  */
 function buildH2Request(client, current, target) {
   const o = client.options;
-  const headers = new Headers(current.headers);
+  const headers = new OrderedHeaders(current.headers);
   const defaultPort = current.url.protocol === 'https:' ? 443 : 80;
   const authority =
     target.port === defaultPort ? current.url.hostname : `${current.url.hostname}:${target.port}`;
 
+  // Profile headers are defaults: a request that sets its own User-Agent keeps it.
+  for (const [name, value] of client.options.profileHeaders ?? []) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
   if (!headers.has('accept')) headers.set('accept', '*/*');
   if (!headers.has('accept-encoding') && o.decompress !== false) {
     headers.set('accept-encoding', acceptEncodingFor(o.decoders));
@@ -747,12 +778,12 @@ function buildH2Request(client, current, target) {
   else if (['POST', 'PUT', 'PATCH'].includes(current.method)) headers.set('content-length', '0');
   else headers.delete('content-length');
 
-  // Headers iterates lowercased (RFC 9113 s8.2.1 requires lowercase names on the wire) — which is
-  // also why h1 loses caller order; h2 is no different here. Pseudo-header ORDER, the part a
-  // fingerprinter reads, is fixed in http2/connection.js buildRequestFields, not here.
-  const out = [];
-  for (const [k, v] of headers) out.push([k, v]);
-  return { authority, headers: out };
+  // Lowercased at the last moment, and only here: RFC 9113 s8.2.1 REQUIRES lowercase field names
+  // on an h2 wire and a server must treat an uppercase one as malformed. h1 is the opposite — real
+  // clients send `Host:`, not `host:` — which is why the case is carried this far and dropped only
+  // on this path. Pseudo-header order is fixed in http2/connection.js buildRequestFields.
+  headers.reorder(o.headerOrder ?? CURL_HEADER_ORDER);
+  return { authority, headers: headers.lowercased() };
 }
 
 function wantsKeepAlive(headInfo) {
@@ -803,13 +834,19 @@ function requestTarget(url) {
 }
 
 function buildHeaders(client, current, target) {
-  const headers = new Headers(current.headers);
+  const headers = new OrderedHeaders(current.headers);
   // Host is derived from the URL and never carried across a redirect; the default port is omitted
   // because a server matching virtual hosts on the literal Host value expects it that way.
   const defaultPort = current.url.protocol === 'https:' ? 443 : 80;
   const hostValue =
     target.port === defaultPort ? current.url.hostname : `${current.url.hostname}:${target.port}`;
 
+  // Profile headers are defaults: a request that sets its own User-Agent keeps it. Applied on both
+  // the h1 and h2 paths, which build their headers separately — the h2 side had this and the h1
+  // side did not, so a profile's User-Agent reached an h2 request and vanished from an h1 one.
+  for (const [name, value] of client.options.profileHeaders ?? []) {
+    if (!headers.has(name)) headers.set(name, value);
+  }
   if (!headers.has('accept')) headers.set('accept', '*/*');
   if (!headers.has('accept-encoding') && client.options.decompress !== false) {
     // Never advertise br or zstd: the runtime has no DecompressionStream for either, so the
@@ -838,12 +875,11 @@ function buildHeaders(client, current, target) {
   else if (['POST', 'PUT', 'PATCH'].includes(current.method)) headers.set('content-length', '0');
   else headers.delete('content-length');
 
-  const ordered = [['host', hostValue]];
-  for (const [k, v] of headers) {
-    if (k === 'host') continue;
-    ordered.push([k, v]);
-  }
-  return ordered;
+  // Host is set rather than prepended so the order below decides where it goes — which for curl
+  // is first, but for a caller matching something else may not be.
+  headers.set('Host', hostValue);
+  headers.reorder(client.options.headerOrder ?? CURL_HEADER_ORDER);
+  return headers.entries();
 }
 
 export { CookieJar, ConnectionPool, utf8 };

package/src/http2/connection.js

@@ -117,6 +117,13 @@ export class Http2Retryable extends Http2Error {}
  * @property {number} [maxConcurrentStreams] our advertised SETTINGS_MAX_CONCURRENT_STREAMS.
  * @property {number} [maxHeaderTableSize] our advertised SETTINGS_HEADER_TABLE_SIZE.
  * @property {number} [maxHeaderListSize] self-protection cap on a decoded response header list.
+ * @property {string[]} [pseudoHeaderOrder] request pseudo-headers in the order to emit them.
+ *   Defaults to curl's `[':method', ':scheme', ':authority', ':path']`. Any of the four left out is
+ *   appended rather than dropped — RFC 9113 s8.3.1 makes all four mandatory and a request missing
+ *   one is malformed, which is not a fingerprint choice anyone should be able to make by accident.
+ * @property {Record<string, 'incremental'|'without'|'never'>} [hpackIndexing] per-field HPACK
+ *   indexing. Which fields enter the dynamic table is part of the fingerprint. Defaults to curl's:
+ *   everything incremental except `:path`, which is sent without indexing.
  * @property {Array<[number, number]>} [settings] the SETTINGS flight sent in the connection
  *   preface, as [id, value] pairs. Order is significant — an Akamai-style HTTP/2 fingerprint reads
  *   the ids in the order they are sent — so this replaces the flight entirely rather than merging.
@@ -202,6 +209,10 @@ export class Http2Connection {
     this._maxHeaderBlockBytes = opts.maxHeaderBlockBytes ?? 262144;
     /** @type {Array<[number, number]> | null} the SETTINGS flight, ids and order included */
     this._settingsFlight = opts.settings ?? null;
+    // The rest of what an Akamai-style h2 fingerprint reads: the pseudo-header order and which
+    // fields go into the HPACK dynamic table. Both default to curl's, both captured off the wire.
+    this._pseudoHeaderOrder = opts.pseudoHeaderOrder ?? null;
+    this._hpackIndexing = opts.hpackIndexing ?? null;
     this._expectFirstSettings = true;
 
     this._fatal = null; // set once; rejects every stream and every future request
@@ -321,7 +332,10 @@ export class Http2Connection {
     }
     const hasBody = body != null && body.byteLength > 0;
 
-    const fields = buildRequestFields({ method, scheme, authority, path, headers });
+    const fields = buildRequestFields(
+      { method, scheme, authority, path, headers },
+      { pseudoHeaderOrder: this._pseudoHeaderOrder, hpackIndexing: this._hpackIndexing },
+    );
     const block = encodeHeaderBlock(fields);
     this._sendHeaderBlock(id, block, !hasBody);
     stream.localEnded = !hasBody;
@@ -1206,14 +1220,32 @@ export class Http2Connection {
  *   headers: Array<[string, string]> }} req
  * @returns {import('./hpack.js').HpackField[]}
  */
-export function buildRequestFields({ method, scheme, authority, path, headers }) {
+export function buildRequestFields({ method, scheme, authority, path, headers }, opts = {}) {
   const pseudo = { ':method': method, ':scheme': scheme, ':authority': authority, ':path': path };
+  const order = opts.pseudoHeaderOrder ?? PSEUDO_HEADER_ORDER;
+  // Which fields go into the dynamic table is itself part of the fingerprint: an Akamai-style h2
+  // hash reads the HPACK representation, and curl indexes everything except :path. A caller
+  // matching another client needs both this and the order, so both are configurable — with the
+  // caller's map consulted first and curl's rule as the default.
+  const indexingFor = (name) =>
+    opts.hpackIndexing?.[name] ?? (name === ':path' ? 'without' : 'incremental');
+
   const fields = [];
+  const seen = new Set();
+  for (const name of order) {
+    if (!(name in pseudo) || seen.has(name)) continue;
+    seen.add(name);
+    fields.push({ name, value: pseudo[name], indexing: indexingFor(name) });
+  }
+  // A caller-supplied order that omits a pseudo-header would produce a malformed request
+  // (RFC 9113 s8.3.1 makes all four mandatory for a request), so the missing ones are appended in
+  // curl's order rather than silently dropped.
   for (const name of PSEUDO_HEADER_ORDER) {
-    fields.push({ name, value: pseudo[name], indexing: name === ':path' ? 'without' : 'incremental' });
+    if (seen.has(name)) continue;
+    fields.push({ name, value: pseudo[name], indexing: indexingFor(name) });
   }
   for (const [name, value] of headers) {
-    fields.push({ name, value, indexing: 'incremental' });
+    fields.push({ name, value, indexing: indexingFor(name) });
   }
   return fields;
 }

package/src/index.js

@@ -44,3 +44,4 @@ import { createFetch } from './client.js';
  * platform's own fetch cannot serve; see the README for why that is not defaulted.
  */
 export const fetch = createFetch();
+export { profiles, curl, chrome, applyProfile } from './profiles.js';

package/src/profiles.js

@@ -0,0 +1,150 @@
+// Fingerprint profiles: one coherent network identity, instead of a dozen knobs that can disagree.
+//
+// Every field a fingerprinter reads is individually configurable — cipher list, groups, signature
+// algorithms, ALPN, TLS versions, ClientHello extension order, GREASE, request header order,
+// HTTP/2 SETTINGS, pseudo-header order, HPACK indexing, Accept-Encoding. That is necessary and it
+// is also a trap: nothing stopped a caller assembling a Chrome User-Agent on top of curl's TLS and
+// curl's HTTP/2, which is a combination no real client produces and a detector reads instantly.
+//
+// A profile is the whole identity or none of it. It supplies defaults for every layer at once, and
+// it declares what it REQUIRES — because a profile that quietly drops the half of itself this
+// runtime cannot perform would recreate exactly the incoherence it exists to prevent.
+//
+// The values are captured, not recalled. curl 8.21.0 / OpenSSL 3.6.3 and Chromium, both read off
+// the wire on 2026-08-01. See test/tls/fingerprint.test.js and test/tls/grease.test.js.
+
+import { ConfigError, codes } from './errors.js';
+import { CURL_EXTENSION_ORDER, SHUFFLE_EXTENSIONS } from './tls/handshake-messages.js';
+import { CURL_HEADER_ORDER } from './client/header-order.js';
+
+/**
+ * @typedef {object} FingerprintProfile
+ * @property {string} name
+ * @property {object} [tls] merged into `tls`
+ * @property {readonly string[]} [headerOrder]
+ * @property {Array<[number, number]>} [http2Settings]
+ * @property {string[]} [http2PseudoHeaderOrder]
+ * @property {Record<string, string>} [http2HpackIndexing]
+ * @property {Array<[string, string]>} [headers] default request headers, in order
+ * @property {string[]} [requires] capabilities the caller must inject for this identity to be
+ *   honest: `'cipher:chacha20'`, `'group:x25519mlkem768'`, `'decoder:br'`, `'decoder:zstd'`
+ */
+
+/**
+ * curl 8.21.0 / OpenSSL 3.6.3. Complete: every layer was captured, and everything it offers is
+ * something this package can actually perform. This is the default identity.
+ */
+export const curl = Object.freeze({
+  name: 'curl/8.21.0',
+  tls: Object.freeze({
+    alpn: ['h2', 'http/1.1'],
+    extensionOrder: CURL_EXTENSION_ORDER,
+    grease: false, // curl does not GREASE
+  }),
+  headerOrder: CURL_HEADER_ORDER,
+  headers: Object.freeze([['User-Agent', 'curl/8.21.0']]),
+  // Captured: MAX_CONCURRENT_STREAMS, INITIAL_WINDOW_SIZE, ENABLE_PUSH, in that order.
+  http2Settings: Object.freeze([[3, 100], [4, 10485760], [2, 0]]),
+  http2PseudoHeaderOrder: Object.freeze([':method', ':scheme', ':authority', ':path']),
+  http2HpackIndexing: Object.freeze({ ':path': 'without' }),
+  requires: Object.freeze([]),
+});
+
+/**
+ * Chromium, TLS layer captured off the wire.
+ *
+ * INCOMPLETE ON PURPOSE, and it refuses to be used as though it were not. Two things are missing
+ * and neither can be papered over:
+ *
+ *   * Chromium offers TLS_CHACHA20_POLY1305_SHA256 and the X25519MLKEM768 group, and this package
+ *     implements neither. A ClientHello is an OFFER: a server may take either, and a client that
+ *     then cannot complete the handshake has traded a fingerprint mismatch for a dead connection.
+ *     Both are reachable by injection, which is why they are listed in `requires` rather than
+ *     silently dropped.
+ *   * Chromium's HTTP/2 preface was not captured — capturing it needs a TLS server the browser
+ *     will trust, which is a different exercise. So this profile carries no h2 layer, and using it
+ *     with HTTP/2 enabled would produce a Chromium ClientHello above a curl h2 preface: precisely
+ *     the split identity a profile exists to prevent.
+ *
+ * `applyProfile` refuses both cases with a message naming what is missing.
+ */
+export const chrome = Object.freeze({
+  name: 'chromium (TLS layer only)',
+  tls: Object.freeze({
+    // 16 suites, GREASE excluded — it is added by the grease option, not carried in the list.
+    ciphers: Object.freeze([
+      0x1301, 0x1302, 0x1303, 0xc02b, 0xc02f, 0xc02c, 0xc030, 0xcca9,
+      0xcca8, 0xc013, 0xc014, 0x009c, 0x009d, 0x002f, 0x0035,
+    ]),
+    groups: Object.freeze([0x11ec, 0x001d, 0x0017, 0x0018]),
+    sigSchemes: Object.freeze([0x0403, 0x0804, 0x0401, 0x0503, 0x0805, 0x0501, 0x0806, 0x0601]),
+    alpn: ['h2', 'http/1.1'],
+    // Measured: two hellos, identical extension set, entirely different orders. Chromium shuffles.
+    extensionOrder: SHUFFLE_EXTENSIONS,
+    grease: true,
+  }),
+  headers: Object.freeze([['Accept-Encoding', 'gzip, deflate, br, zstd']]),
+  http2Settings: null, // not captured — see above
+  requires: Object.freeze([
+    'cipher:chacha20',
+    'group:x25519mlkem768',
+    'decoder:br',
+    'decoder:zstd',
+    'http2:captured',
+  ]),
+});
+
+/** @type {Record<string, FingerprintProfile>} */
+export const profiles = Object.freeze({ curl, chrome });
+
+/**
+ * Fold a profile into a Client's options, and refuse an identity that cannot be honoured.
+ *
+ * Explicit options WIN over the profile: a caller who names a field meant to name it, and silently
+ * overriding them would make the profile impossible to adjust. The profile fills what was not said.
+ *
+ * @param {object} options as given to the Client
+ * @returns {object} options with the profile folded in
+ */
+export function applyProfile(options) {
+  const p = options.profile;
+  if (!p) return options;
+  if (typeof p !== 'object' || !p.name) {
+    throw new ConfigError(
+      codes.CONFIG_INVALID,
+      'profile must be a fingerprint profile object; see `profiles` for the built-in ones',
+    );
+  }
+
+  const missing = [];
+  for (const need of p.requires ?? []) {
+    const [kind, what] = need.split(':');
+    if (kind === 'decoder' && !options.decoders?.[what]) missing.push(need);
+    if (kind === 'cipher' && !options.ciphers?.[what]) missing.push(need);
+    if (kind === 'group' && !options.groups?.[what]) missing.push(need);
+    // A profile with no captured h2 layer must not be run over HTTP/2, or it presents this
+    // identity's ClientHello above a different client's preface.
+    if (kind === 'http2' && options.http2 !== false) missing.push(need);
+  }
+  if (missing.length) {
+    throw new ConfigError(
+      codes.CONFIG_INVALID,
+      `the "${p.name}" profile cannot be presented honestly: ${missing.join(', ')} ` +
+        `${missing.length === 1 ? 'is' : 'are'} missing. A fingerprint field this package cannot ` +
+        'perform is an offer a server may take and then find unhonoured, which fails the ' +
+        'connection rather than merely looking wrong. Supply the missing pieces (see `decoders`, ' +
+        '`ciphers`, `groups`) or set `http2: false`, or use a profile that is complete.',
+      { profile: p.name, missing },
+    );
+  }
+
+  const out = { ...options };
+  if (p.tls) out.tls = { ...p.tls, ...(options.tls ?? {}) };
+  for (const key of ['headerOrder', 'http2Settings', 'http2PseudoHeaderOrder', 'http2HpackIndexing']) {
+    if (options[key] === undefined && p[key] != null) out[key] = p[key];
+  }
+  // Profile headers are DEFAULTS: a request that sets its own User-Agent keeps it. They are folded
+  // in per request rather than here, so this only records them.
+  if (p.headers) out.profileHeaders = p.headers;
+  return out;
+}

package/src/tls/connect.js

@@ -136,7 +136,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
@@ -334,6 +339,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/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,6 +11,7 @@
 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';
@@ -49,6 +50,7 @@ import {
   encodePreSharedKey,
   encodePskKeyExchangeModes,
   encodeRenegotiationInfo,
+  encodeRawExtension,
   encodeServerName,
   encodeSignatureAlgorithms,
   encodeStatusRequest,
@@ -230,6 +232,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 +287,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 +315,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 +333,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 +359,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 +549,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,

package/src/tls/handshake.js

@@ -243,6 +243,7 @@ export async function continueTls13(ctx) {
       // either among the modifications a second ClientHello may make, and a strict server checks.
       extensionOrder: options.extensionOrder,
       sigSchemes: options.sigSchemes,
+      grease: options.grease ?? false,
       random: hello.clientRandom,
       legacySessionId: hello.legacySessionId,
       extraExtensions: cookie ? [cookieExtension(cookie)] : [],

package/types/client/header-order.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Read the caller's header names in the order and case they wrote them, BEFORE anything hands them
+ * to `Request`, which is where both are lost.
+ *
+ * Recovers what is recoverable and no more: an array of pairs or a plain object still carries the
+ * caller's order, a `Headers` or a `Request` does not — those were normalised before this package
+ * ever saw them, and there is nothing here to reconstruct.
+ *
+ * @param {RequestInfo | URL} input
+ * @param {RequestInit} [init]
+ * @returns {Array<[string, string]> | null} null when the caller's order was already gone
+ */
+export function callerHeaderOrder(input: RequestInfo | URL, init?: RequestInit): Array<[string, string]> | null;
+/**
+ * Default request header order, from curl 8.21.0 on the wire. `'*'` is where headers not named
+ * here go, in the order they were given — which is where curl puts the caller's own.
+ */
+export const CURL_HEADER_ORDER: readonly string[];
+/**
+ * An ordered, case-preserving header list.
+ *
+ * Deliberately not a `Headers` subclass and deliberately not backed by one: the whole point is to
+ * be the thing `Headers` is not. Lookup and mutation are case-insensitive, as HTTP requires;
+ * iteration returns names exactly as they were written, in the order they arrived.
+ */
+export class OrderedHeaders {
+    /** @param {Headers | Iterable<[string, string]> | Record<string, string> | null} [init] */
+    constructor(init?: Headers | Iterable<[string, string]> | Record<string, string> | null);
+    /** @type {Array<[string, string]>} name as written, value */
+    _list: Array<[string, string]>;
+    _indexOf(name: any): number;
+    has(name: any): boolean;
+    /** Comma-joined when a field appears more than once, matching `Headers.get`. */
+    get(name: any): string | null;
+    /**
+     * Replace IN PLACE when the field is already present, so setting a value does not move a header
+     * to the end and silently reorder the request. A caller who wrote `User-Agent` first and then
+     * had it overwritten should still see it first.
+     */
+    set(name: any, value: any): void;
+    append(name: any, value: any): void;
+    delete(name: any): void;
+    /**
+     * Put the fields into `order`, which names lowercased header names and may contain `'*'` to mark
+     * where everything unnamed goes. Fields keep their relative order within each group, so a
+     * caller's own sequence survives.
+     *
+     * @param {readonly string[]} order
+     */
+    reorder(order: readonly string[]): void;
+    /** @returns {Array<[string, string]>} names as written, in order */
+    entries(): Array<[string, string]>;
+    /** Lowercased names, for HTTP/2 where RFC 9113 s8.2.1 requires them. */
+    lowercased(): string[][];
+    [Symbol.iterator](): ArrayIterator<[string, string]>;
+}

package/types/client.d.ts

@@ -65,6 +65,20 @@ export function install(options?: ClientOptions): () => void;
  *   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 {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
+ *   together. Explicit options win over it. A profile that declares capabilities this package
+ *   cannot perform is REFUSED rather than silently reduced: see `profiles.chrome`.
+ * @property {readonly string[]} [headerOrder] request header names, lowercased, in the order to
+ *   emit them; `'*'` marks where headers not named go, in the order the caller gave them. Defaults
+ *   to curl's (`CURL_HEADER_ORDER`). The platform `Headers` sorts alphabetically and lowercases, so
+ *   without this a request goes out with `user-agent` last, which no real client does.
+ * @property {string[]} [http2PseudoHeaderOrder] request pseudo-headers in the order to emit them.
+ *   Defaults to curl's. Any of the four omitted is appended rather than dropped: RFC 9113 s8.3.1
+ *   makes all four mandatory, so a request missing one is malformed rather than merely unusual.
+ * @property {Record<string, 'incremental'|'without'|'never'>} [http2HpackIndexing] per-field HPACK
+ *   indexing. Which fields enter the dynamic table is read by an Akamai-style h2 fingerprint.
+ *   Defaults to curl's: everything incremental except `:path`.
  * @property {Array<[number, number]>} [http2Settings] the HTTP/2 SETTINGS flight, as [id, value]
  *   pairs. Order is significant — an Akamai-style h2 fingerprint reads the ids in the order they
  *   are sent — so this replaces the flight rather than merging into it. Defaults to curl's. The
@@ -227,6 +241,32 @@ export type ClientOptions = {
      * default true.
      */
     keepAlive?: boolean | undefined;
+    /**
+     * one coherent network identity
+     * instead of a dozen knobs that can disagree — TLS, HTTP/2, header order and default headers
+     * together. Explicit options win over it. A profile that declares capabilities this package
+     * cannot perform is REFUSED rather than silently reduced: see `profiles.chrome`.
+     */
+    profile?: import("./profiles.js").FingerprintProfile | undefined;
+    /**
+     * request header names, lowercased, in the order to
+     * emit them; `'*'` marks where headers not named go, in the order the caller gave them. Defaults
+     * to curl's (`CURL_HEADER_ORDER`). The platform `Headers` sorts alphabetically and lowercases, so
+     * without this a request goes out with `user-agent` last, which no real client does.
+     */
+    headerOrder?: readonly string[] | undefined;
+    /**
+     * request pseudo-headers in the order to emit them.
+     * Defaults to curl's. Any of the four omitted is appended rather than dropped: RFC 9113 s8.3.1
+     * makes all four mandatory, so a request missing one is malformed rather than merely unusual.
+     */
+    http2PseudoHeaderOrder?: string[] | undefined;
+    /**
+     * per-field HPACK
+     * indexing. Which fields enter the dynamic table is read by an Akamai-style h2 fingerprint.
+     * Defaults to curl's: everything incremental except `:path`.
+     */
+    http2HpackIndexing?: Record<string, "without" | "incremental" | "never"> | undefined;
     /**
      * the HTTP/2 SETTINGS flight, as [id, value]
      * pairs. Order is significant — an Akamai-style h2 fingerprint reads the ids in the order they

package/types/http2/connection.d.ts

@@ -13,7 +13,7 @@ export function buildRequestFields({ method, scheme, authority, path, headers }:
     authority: string;
     path: string;
     headers: Array<[string, string]>;
-}): import("./hpack.js").HpackField[];
+}, opts?: {}): import("./hpack.js").HpackField[];
 /**
  * @typedef {ReadableStream<Uint8Array> & { completed: Promise<boolean>,
  *   trailers: Promise<Headers | null> }} BodyStream
@@ -76,6 +76,8 @@ export class Http2Connection {
     _maxHeaderBlockBytes: number;
     /** @type {Array<[number, number]> | null} the SETTINGS flight, ids and order included */
     _settingsFlight: Array<[number, number]> | null;
+    _pseudoHeaderOrder: string[] | null;
+    _hpackIndexing: Record<string, "without" | "incremental" | "never"> | null;
     _expectFirstSettings: boolean;
     _fatal: any;
     _goaway: {
@@ -254,6 +256,19 @@ export type Http2ConnectionOptions = {
      * self-protection cap on a decoded response header list.
      */
     maxHeaderListSize?: number | undefined;
+    /**
+     * request pseudo-headers in the order to emit them.
+     * Defaults to curl's `[':method', ':scheme', ':authority', ':path']`. Any of the four left out is
+     * appended rather than dropped — RFC 9113 s8.3.1 makes all four mandatory and a request missing
+     * one is malformed, which is not a fingerprint choice anyone should be able to make by accident.
+     */
+    pseudoHeaderOrder?: string[] | undefined;
+    /**
+     * per-field HPACK
+     * indexing. Which fields enter the dynamic table is part of the fingerprint. Defaults to curl's:
+     * everything incremental except `:path`, which is sent without indexing.
+     */
+    hpackIndexing?: Record<string, "without" | "incremental" | "never"> | undefined;
     /**
      * the SETTINGS flight sent in the connection
      * preface, as [id, value] pairs. Order is significant — an Akamai-style HTTP/2 fingerprint reads

package/types/http2/hpack.d.ts

@@ -79,7 +79,7 @@ export type HpackField = {
      * how to represent it when it is not a
      * full static match. Default 'incremental', which is what curl uses for most fields.
      */
-    indexing?: "incremental" | "without" | "never" | undefined;
+    indexing?: "without" | "incremental" | "never" | undefined;
 };
 export type HpackDecoderOptions = {
     /**

package/types/index.d.ts

@@ -15,3 +15,4 @@ export { openConnection, targetFromUrl, nativeFetchCanServe } from "./transport.
 export { openTunnel, parseProxy } from "./proxy/index.js";
 export { verifyChain, rootStoreProvenance } from "./trust/index.js";
 export { TunnelFetchError, ProxyError, HttpError, TlsError, TlsUnsupportedError, Http2Error, CertificateError, TimeoutError, LimitError, ConfigError, codes } from "./errors.js";
+export { profiles, curl, chrome, applyProfile } from "./profiles.js";

package/types/profiles.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Fold a profile into a Client's options, and refuse an identity that cannot be honoured.
+ *
+ * Explicit options WIN over the profile: a caller who names a field meant to name it, and silently
+ * overriding them would make the profile impossible to adjust. The profile fills what was not said.
+ *
+ * @param {object} options as given to the Client
+ * @returns {object} options with the profile folded in
+ */
+export function applyProfile(options: object): object;
+/**
+ * @typedef {object} FingerprintProfile
+ * @property {string} name
+ * @property {object} [tls] merged into `tls`
+ * @property {readonly string[]} [headerOrder]
+ * @property {Array<[number, number]>} [http2Settings]
+ * @property {string[]} [http2PseudoHeaderOrder]
+ * @property {Record<string, string>} [http2HpackIndexing]
+ * @property {Array<[string, string]>} [headers] default request headers, in order
+ * @property {string[]} [requires] capabilities the caller must inject for this identity to be
+ *   honest: `'cipher:chacha20'`, `'group:x25519mlkem768'`, `'decoder:br'`, `'decoder:zstd'`
+ */
+/**
+ * curl 8.21.0 / OpenSSL 3.6.3. Complete: every layer was captured, and everything it offers is
+ * something this package can actually perform. This is the default identity.
+ */
+export const curl: Readonly<{
+    name: "curl/8.21.0";
+    tls: Readonly<{
+        alpn: string[];
+        extensionOrder: readonly number[];
+        grease: false;
+    }>;
+    headerOrder: readonly string[];
+    headers: readonly string[][];
+    http2Settings: readonly number[][];
+    http2PseudoHeaderOrder: readonly string[];
+    http2HpackIndexing: Readonly<{
+        ':path': "without";
+    }>;
+    requires: readonly never[];
+}>;
+/**
+ * Chromium, TLS layer captured off the wire.
+ *
+ * INCOMPLETE ON PURPOSE, and it refuses to be used as though it were not. Two things are missing
+ * and neither can be papered over:
+ *
+ *   * Chromium offers TLS_CHACHA20_POLY1305_SHA256 and the X25519MLKEM768 group, and this package
+ *     implements neither. A ClientHello is an OFFER: a server may take either, and a client that
+ *     then cannot complete the handshake has traded a fingerprint mismatch for a dead connection.
+ *     Both are reachable by injection, which is why they are listed in `requires` rather than
+ *     silently dropped.
+ *   * Chromium's HTTP/2 preface was not captured — capturing it needs a TLS server the browser
+ *     will trust, which is a different exercise. So this profile carries no h2 layer, and using it
+ *     with HTTP/2 enabled would produce a Chromium ClientHello above a curl h2 preface: precisely
+ *     the split identity a profile exists to prevent.
+ *
+ * `applyProfile` refuses both cases with a message naming what is missing.
+ */
+export const chrome: Readonly<{
+    name: "chromium (TLS layer only)";
+    tls: Readonly<{
+        ciphers: readonly number[];
+        groups: readonly number[];
+        sigSchemes: readonly number[];
+        alpn: string[];
+        extensionOrder: "shuffle";
+        grease: true;
+    }>;
+    headers: readonly string[][];
+    http2Settings: null;
+    requires: readonly string[];
+}>;
+/** @type {Record<string, FingerprintProfile>} */
+export const profiles: Record<string, FingerprintProfile>;
+export type FingerprintProfile = {
+    name: string;
+    /**
+     * merged into `tls`
+     */
+    tls?: object | undefined;
+    headerOrder?: readonly string[] | undefined;
+    http2Settings?: [number, number][] | undefined;
+    http2PseudoHeaderOrder?: string[] | undefined;
+    http2HpackIndexing?: Record<string, string> | undefined;
+    /**
+     * default request headers, in order
+     */
+    headers?: [string, string][] | undefined;
+    /**
+     * capabilities the caller must inject for this identity to be
+     * honest: `'cipher:chacha20'`, `'group:x25519mlkem768'`, `'decoder:br'`, `'decoder:zstd'`
+     */
+    requires?: string[] | undefined;
+};

package/types/tls/connect.d.ts

@@ -15,7 +15,12 @@
  *   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
@@ -154,6 +159,14 @@ export type TlsOptions = {
      * signature_algorithms to offer, in preference order.
      */
     sigSchemes?: number[] | undefined;
+    /**
+     * 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.
+     */
+    grease?: number | boolean | undefined;
     /**
      * 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
@@ -161,7 +174,7 @@ export type TlsOptions = {
      * natural position at the end; `pre_shared_key` is always last whatever is asked, because RFC
      * 8446 s4.2.11 defines the binder transcript as the hello truncated just before the binders.
      */
-    extensionOrder?: number[] | undefined;
+    extensionOrder?: number[] | "shuffle" | undefined;
     /**
      * fixed ClientHello.random, for reproducible handshakes.
      */

package/types/tls/extensions.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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: number, body: Uint8Array): Uint8Array<ArrayBufferLike>;
 /**
  * server_name (RFC 6066). Only host_name (type 0) exists in practice.
  * An IP literal must NOT be sent as SNI — RFC 6066 s3 forbids it, and servers that do virtual

package/types/tls/grease.d.ts

@@ -0,0 +1,46 @@
+/** @param {number} v @returns {boolean} */
+export function isGrease(v: number): boolean;
+/**
+ * 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: number): {
+    /** A GREASE value not yet handed out in this hello, since Chromium never repeats one. */
+    take(): number;
+    next: () => number;
+};
+/**
+ * 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: Array<Uint8Array>, rng: {
+    next: () => number;
+}, typeOf: (e: Uint8Array) => number, pskType: number): Array<Uint8Array>;
+/**
+ * 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: number): {
+    group: number;
+    keyExchange: Uint8Array<ArrayBuffer>;
+};
+/** The sixteen reserved values (RFC 8701 s2): 0x0A0A, 0x1A1A, ... 0xFAFA. */
+export const GREASE_VALUES: readonly number[];

package/types/tls/handshake-messages.d.ts

@@ -28,7 +28,7 @@ export function generateKeyShare(group: number, { generateKeyPair }?: import("./
  * @returns {Promise<Uint8Array>} throws on any degenerate or malformed peer key
  */
 export function deriveSharedSecret(group: number, privateKey: CryptoKey, peerKey: Uint8Array): Promise<Uint8Array>;
-export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extensionOrder, extraExtensions, psk, randomBytes, }: {
+export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extensionOrder, extraExtensions, psk, grease, randomBytes, }: {
     hostname: any;
     keyShares: any;
     random: any;
@@ -41,6 +41,7 @@ export function buildClientHello({ hostname, keyShares, random, legacySessionId,
     extensionOrder?: readonly number[] | undefined;
     extraExtensions?: never[] | undefined;
     psk?: null | undefined;
+    grease?: boolean | undefined;
     randomBytes?: ((n: any) => Uint8Array<any>) | undefined;
 }): {
     message: Uint8Array<ArrayBufferLike>;
@@ -351,6 +352,8 @@ export function checkAlpn(extensions: Map<number, Uint8Array>, offeredAlpn: stri
  * 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: readonly number[];
 export { GROUP_PARAMS };
 /**