tunnelfetch 1.1.2 → 1.3.0

package/README.md

@@ -311,10 +311,53 @@ behaviour — measure your own targets, and expect the answer to change. Our TLS
 identical outcomes on every reachable host in that sample, so JA3-style TLS shaping is not what
 gates access here — but curl's **HTTP/2** fingerprint passed where HTTP/1.1 was challenged. So the
 `SETTINGS` frame values, the initial window sizes, the connection `WINDOW_UPDATE`, and the
-pseudo-header order are matched byte-for-byte to curl (8.7.1 / nghttp2), captured off the wire.
+pseudo-header order are matched byte-for-byte to curl (nghttp2 1.69.0), captured off the wire.
 This is empirical: a naïve h2 fingerprint can fail exactly where curl's succeeds, which would waste
 the whole exercise.
 
+### Fingerprints
+
+Both halves are matched to **curl 8.21.0 / OpenSSL 3.6.3** and both are fully configurable. The TLS
+backend matters more than the curl version — the same curl built against SecureTransport produces a
+completely different ClientHello — so the reference is captured off the wire, not recalled, and
+pinned in `test/tls/fingerprint.test.js` and `test/http2/fingerprint.test.js`.
+
+| Layer | Default | Configure with |
+|---|---|---|
+| ClientHello extension **order** | curl's, exactly, for every extension both send | `tls.extensionOrder` |
+| Cipher suites | the AEAD suites this package implements, in curl's relative order | `tls.ciphers` |
+| Supported groups | `x25519, secp256r1, secp384r1, secp521r1` | `tls.groups` |
+| Signature algorithms | ECDSA and RSA-PSS/PKCS#1 over SHA-256/384/512 | `tls.sigSchemes` |
+| ALPN | `h2, http/1.1` | `tls.alpn` |
+| HTTP/2 `SETTINGS` ids **and order** | curl's: `MAX_CONCURRENT_STREAMS, INITIAL_WINDOW_SIZE, ENABLE_PUSH` | `http2Settings` |
+| h2 preface, `WINDOW_UPDATE`, pseudo-header order, HPACK representation | curl's, byte-for-byte | fixed |
+| `Accept-Encoding` | `gzip, deflate` — curl's | `decoders` appends |
+
+Extension order matters because JA3 and JA4 hash the extension list **in wire order**, so it is most
+of what a fingerprinter reads. `pre_shared_key` is forced last whatever you ask for: RFC 8446
+§4.2.11 defines the binder transcript as the hello truncated just before the binders, which is a
+well-defined byte range only if nothing follows them.
+
+**Where the default deliberately differs from curl**, and why it cannot simply be copied: a
+ClientHello is an *offer*, and a server may take you up on any of it. Advertising what you cannot do
+trades a fingerprint mismatch for a broken handshake, which is worse and fails silently.
+
+| curl sends | This package | Why |
+|---|---|---|
+| 30 cipher suites, incl. RSA key exchange and CBC | 6 AEAD suites | Not implemented, by design. A server selecting `TLS_RSA_WITH_AES_256_CBC_SHA` would get a dead connection |
+| `X25519MLKEM768` group and a 1216-byte key share | not offered | ML-KEM is not implemented |
+| SHA-1 signature schemes | not offered | Refused deliberately |
+| `encrypt_then_mac` | not sent | Applies only to CBC suites, which are not offered |
+| `post_handshake_auth` | not sent | Invites a post-handshake `CertificateRequest`, which is not implemented |
+| — | `status_request` | curl does not ask for a stapled OCSP response; this package must, because a staple is its only revocation signal |
+
+Closing that gap means implementing ML-KEM, RSA key exchange and CBC suites — a different project,
+and the last two are things this package refuses on purpose. `tls.ciphers` and `tls.groups` will let
+you offer them anyway; the handshake will then fail if a server picks one, and that is yours to own.
+
+A test asserts this delta is exactly the list above, so gaining one of these capabilities without
+updating the table fails the build.
+
 Everything an HTTP/1.1 body has, an HTTP/2 body keeps: streaming (SSE works unchanged), trailers,
 gzip decoding, and the idle deadline wrapping the raw body before any decode. The one thing that is
 structurally different is under the hood — a single h2 connection multiplexes every concurrent

package/README.zh-CN.md

@@ -251,6 +251,38 @@ TLS 指纹塑形不是这里的门槛——但 curl 的 **HTTP/2** 指纹能过
 curl（8.7.1 / nghttp2），照线上抓包原样复刻。这么做是实证需要，不是讲究：一个想当然的 h2
 指纹，可能恰好败在 curl 能过的地方——那这整件事就白做了。
 
+### 指纹
+
+两侧都对齐 **curl 8.21.0 / OpenSSL 3.6.3**，且全部可自定义。TLS 后端比 curl 版本更要紧——同一个 curl 用 SecureTransport 编译出来的 ClientHello 完全不同——所以参照物是从线上抓下来的，不是凭记忆写的，并且钉死在 `test/tls/fingerprint.test.js` 与 `test/http2/fingerprint.test.js` 里。
+
+| 层 | 默认 | 配置项 |
+|---|---|---|
+| ClientHello 扩展**顺序** | 与 curl 完全一致（就双方都发的那些而言） | `tls.extensionOrder` |
+| 密码套件 | 本包实现的 AEAD 套件，按 curl 的相对顺序 | `tls.ciphers` |
+| supported_groups | `x25519, secp256r1, secp384r1, secp521r1` | `tls.groups` |
+| 签名算法 | SHA-256/384/512 上的 ECDSA 与 RSA-PSS/PKCS#1 | `tls.sigSchemes` |
+| ALPN | `h2, http/1.1` | `tls.alpn` |
+| HTTP/2 `SETTINGS` 的 id **与顺序** | curl 的：`MAX_CONCURRENT_STREAMS, INITIAL_WINDOW_SIZE, ENABLE_PUSH` | `http2Settings` |
+| h2 前导、`WINDOW_UPDATE`、伪头顺序、HPACK 表示 | curl 的，逐字节一致 | 固定 |
+| `Accept-Encoding` | `gzip, deflate`——curl 的 | `decoders` 会追加 |
+
+扩展顺序之所以要紧，是因为 JA3 和 JA4 哈希的正是**线上顺序**的扩展列表，那是指纹识别读到的主要内容。`pre_shared_key` 无论你怎么配都强制排最后：RFC 8446 §4.2.11 把 binder 的转录定义为"截到 binder 之前的那段 hello"，只有后面不跟东西时这个范围才成立。
+
+**默认值刻意与 curl 不同的地方**，以及为什么不能照抄：ClientHello 是一份**要约**，服务器可以接受其中任何一项。声明你做不到的事，等于拿指纹不一致换一次握手失败——后者更糟，而且是静默的。
+
+| curl 发送 | 本包 | 原因 |
+|---|---|---|
+| 30 个套件，含 RSA 密钥交换与 CBC | 6 个 AEAD 套件 | 有意不实现。服务器选中 `TLS_RSA_WITH_AES_256_CBC_SHA` 会得到一条死连接 |
+| `X25519MLKEM768` 群及 1216 字节 key share | 不提供 | 未实现 ML-KEM |
+| SHA-1 签名方案 | 不提供 | 明确拒绝 |
+| `encrypt_then_mac` | 不发 | 只对 CBC 套件有意义，而 CBC 不提供 |
+| `post_handshake_auth` | 不发 | 会招来握手后的 `CertificateRequest`，未实现 |
+| — | `status_request` | curl 不索要 OCSP staple；本包必须要，因为 staple 是它唯一的吊销信号 |
+
+要抹平这个差距，得先实现 ML-KEM、RSA 密钥交换和 CBC 套件——那是另一个项目，而且后两者是本包**故意**不做的。`tls.ciphers` 和 `tls.groups` 允许你照样把它们报出去；服务器一旦选中握手就会失败，后果由你自己承担。
+
+有一个测试断言这张差异表**恰好**就是上面这些，所以哪天获得了其中某项能力却没更新这张表，构建会直接失败。
+
 HTTP/1.1 的 body 有的，HTTP/2 的 body 全都保留：流式（SSE 原样可用）、trailer、gzip 解码、
 以及在任何解码之前先包住原始 body 的 idle 截止线。结构上唯一不同的在水面之下——一条 h2 连接把
 发往同一源站的所有并发请求复用在一起，而不是一次签出、一次只服务一个请求。`install()`、重定向、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.1.2",
+  "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,25 @@ 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
+ *   TLS half of the fingerprint is configured through `tls` (`ciphers`, `groups`, `sigSchemes`,
+ *   `alpn`, `versions`, `extensionOrder`).
  * @property {boolean} [http2] offer HTTP/2 via ALPN and speak it when the server selects it.
  *   Default true. The goal is ACCESS, not speed — some sites treat HTTP/1.1 as a bot signal — and
  *   on a CPU-billed runtime h2 costs MORE than h1 (HPACK is extra work). Set false to offer only
@@ -101,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,
@@ -232,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;
@@ -246,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 = [];
@@ -436,6 +462,17 @@ function registerHttp2(client, key, conn) {
     { readable: conn.readable, writable: conn.writable, close: conn.close },
     {
       info: conn.info,
+      // The h2 half of the fingerprint. Passed through so a caller can present some client other
+      // than curl without reaching past the Client for it — the TLS half is configurable through
+      // `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.
@@ -713,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));
@@ -737,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) {
@@ -793,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
@@ -828,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,17 @@ 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.
+ *   Defaults to curl's: MAX_CONCURRENT_STREAMS, INITIAL_WINDOW_SIZE, ENABLE_PUSH.
  * @property {number} [maxHeaderBlockBytes] cap on the RAW bytes of one HEADERS+CONTINUATION run,
  *   before HPACK decoding. Default 262144, matching the decoded cap. This is the bound that stops
  *   a CONTINUATION flood; `maxHeaderListSize` cannot, because it is only reachable once the whole
@@ -196,6 +207,12 @@ export class Http2Connection {
     // reference makes a small input decode LARGER, never the reverse — so a block whose raw size
     // exceeds the decoded cap could not have produced an acceptable header list anyway.
     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
@@ -230,11 +247,19 @@ export class Http2Connection {
   _sendPreface() {
     // Exactly curl's flight and order: the 24-byte magic, then SETTINGS (ids 3,4,2), then a
     // connection-level WINDOW_UPDATE that raises the receive window to 1000 MiB. See constants.js.
-    const settings = settingsFrame([
-      [SETTINGS.MAX_CONCURRENT_STREAMS, this._ourMaxConcurrent],
-      [SETTINGS.INITIAL_WINDOW_SIZE, this._ourInitialWindow],
-      [SETTINGS.ENABLE_PUSH, 0],
-    ]);
+    //
+    // The ORDER of the settings, not just their values, is part of the fingerprint an Akamai-style
+    // h2 hash reads, so a caller matching some other client needs to be able to set both. Supplying
+    // `settings` replaces the flight wholesale; the values still drive this connection's own
+    // behaviour, so a caller who advertises a window it will not honour has misconfigured the
+    // connection rather than merely disguised it.
+    const settings = settingsFrame(
+      this._settingsFlight ?? [
+        [SETTINGS.MAX_CONCURRENT_STREAMS, this._ourMaxConcurrent],
+        [SETTINGS.INITIAL_WINDOW_SIZE, this._ourInitialWindow],
+        [SETTINGS.ENABLE_PUSH, 0],
+      ],
+    );
     const inc = this._ourConnWindow - DEFAULT_INITIAL_WINDOW;
     const flight =
       inc > 0
@@ -307,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;
@@ -1192,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';