tunnelfetch 1.2.0 → 1.4.0

package/README.md

@@ -278,6 +278,32 @@ it saves do not pay it back — see [What this cannot do](#what-this-cannot-do-a
 are validated as HTTP tokens, a decoder that throws fails the body closed rather than truncating it,
 and an unregistered coding is still refused.
 
+### The Chrome identity, in one import
+
+```js
+import { Client } from 'tunnelfetch';
+import { chrome } from 'tunnelfetch/profile/chrome';
+
+const client = new Client({ profile: chrome, connect, proxy, decoders: { br, zstd } });
+```
+
+The subpath carries the two primitives this runtime has no native path for — ML-KEM-768 for the
+`X25519MLKEM768` key exchange and ChaCha20-Poly1305 for the record layer, both compiled to
+freestanding WASM and both with known-answer tests in this repository. **Importing it is the
+opt-in:** a bundler pulls them in only for code on this path, so the default identity carries none
+of it.
+
+`br` and `zstd` stay yours. They are not cryptography and there is no single right implementation,
+so the profile keeps refusing until you supply them — a Chrome that advertises `br` and cannot read
+it is worse than one that says so.
+
+Verified end to end, not merely constructed:
+
+| Origin | | TLS | Group | HTTP |
+|---|---|---|---|---|
+| `blog.cloudflare.com` | 200 | 1.3 | `0x11ec` X25519MLKEM768 | h2 |
+| `www.shopify.com` | 200 | 1.3 | `0x11ec` X25519MLKEM768 | h2 |
+
 ### HTTP/2 — access, not speed
 
 The client offers `h2` and `http/1.1` in ALPN by default and speaks whichever the server selects.
@@ -344,16 +370,19 @@ trades a fingerprint mismatch for a broken handshake, which is worse and fails s
 
 | 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 |
+| 30 cipher suites, incl. ChaCha20, RSA key exchange and CBC | 6 AEAD suites, or 7 with ChaCha20 injected | RSA-kx and CBC are refused by design — a server selecting `TLS_RSA_WITH_AES_256_CBC_SHA` would get a dead connection. `TLS_CHACHA20_POLY1305_SHA256` is injectable via `ciphers: { chacha20 }`: WebCrypto has no ChaCha20 here, so an implementation is supplied rather than a `node:crypto` dependency taken |
+| `X25519MLKEM768` group and a 1216-byte key share | offered only when injected | ML-KEM is not a WebCrypto primitive; supply it as `groups: { x25519mlkem768 }` (what `profiles.chrome` requires) and the group and its 1216-byte hybrid key share go on the wire |
 | 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.
+ChaCha20-Poly1305 and X25519MLKEM768 are reachable by **injection**: an implementation of each is
+supplied through `ciphers` / `groups`, which is precisely what `profiles.chrome` requires, and
+neither is offered unless one is — a suite or group advertised but not performable is a dead
+connection if a server takes it. RSA key exchange and CBC suites stay refused on purpose;
+`tls.ciphers` and `tls.groups` will let you offer them anyway, and the handshake will then fail if a
+server picks one, which 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.
@@ -381,7 +410,9 @@ res.tunnelfetch.httpVersion; // '2' if the server chose h2, '1.1' otherwise
 | `connect` | — | Socket factory. On Workers, the `connect` export of `cloudflare:sockets`. Required for anything the platform's `fetch` cannot serve. |
 | `proxy` | `null` | URL string or object. `http:`, `https:`, `socks5:`, `socks5h:`. |
 | `trust` | `{mode:'system'}` | Certificate policy; see below. |
-| `tls` | `{}` | Handshake options (`alpn`, `groups`, `ciphers`, `offerGroups`). |
+| `tls` | `{}` | Handshake options (`alpn`, `groups`, `ciphers`, `offerGroups`). Here `groups`/`ciphers` are number lists — the suite and group ids to offer, in preference order. |
+| `ciphers` | `{}` | Injected AEAD implementations by capability name: `{ chacha20 }` (a `seal`/`open` pair). WebCrypto has no ChaCha20 here, so `TLS_CHACHA20_POLY1305_SHA256` is offered only when this is supplied. Required by `profiles.chrome`. |
+| `groups` | `{}` | Injected key-exchange implementations by capability name: `{ x25519mlkem768 }` (ML-KEM-768 `keygen`/`encapsulate`/`decapsulate`). ML-KEM is not a WebCrypto primitive, so the post-quantum hybrid group is offered only when this is supplied. Required by `profiles.chrome`. |
 | `timeouts` | see below | `connectMs`, `handshakeMs`, `headersMs`, `idleMs`, `totalMs`. |
 | `cookies` | `false` | Enable a per-Client cookie jar. |
 | `maxRedirects` | `20` | |
@@ -493,9 +524,15 @@ Not implemented, and not planned:
   since 2020. Note the distinction: a server that *also* supports 1.0/1.1 is fine, because we will
   negotiate 1.2 or 1.3 with it. Only a server that supports *nothing else* is out of reach.
 - **RSA key transport.** No forward secrecy.
-- **ChaCha20-Poly1305.** It buys nothing: a server can only pick a suite we offered, TLS 1.3
-  mandates AES-128-GCM, and AES-GCM is universal in TLS 1.2 deployments. WebCrypto has no
-  ChaCha20, so offering it would mean a `node:crypto` dependency for zero compatibility gain.
+- **ChaCha20-Poly1305, unless injected.** WebCrypto has no ChaCha20 on this runtime, so it is not
+  built in — taking a `node:crypto` dependency would cost the package its "web platform only"
+  property. It is *injectable*, though: pass `ciphers: { chacha20 }` (a `seal`/`open` pair, e.g. a
+  WASM build) and `TLS_CHACHA20_POLY1305_SHA256` is offered — in curl's captured position, second
+  after AES-256-GCM — and used. Not built in because a server can only pick a suite we offered, TLS
+  1.3 mandates AES-128-GCM, and AES-GCM is universal in TLS 1.2; the reason to add it is matching a
+  browser that offers it (`profiles.chrome`), not compatibility. The post-quantum
+  **X25519MLKEM768** group is injectable the same way — `groups: { x25519mlkem768 }` — for the same
+  reason: ML-KEM is not a WebCrypto primitive here.
 - **Client certificates (mTLS), 0-RTT, renegotiation.** A `HelloRequest` is refused rather than
   honoured. 0-RTT is a decision rather than an omission: early data can be replayed, so offering
   it would let an attacker who captured a POST replay it. (Session resumption itself *is*
@@ -565,25 +602,28 @@ Fetching a size-controlled origin through a proxy, warm, medians over seven-plus
 isolate, gzip on the wire. The last column is the same numbers as a rate, which is the form worth
 carrying around:
 
-| | New connection | Each further request, same connection | Marginal rate |
-| --- | --- | --- | --- |
-| 1 KB body | 11 ms | 2–3 ms | — |
-| 16 KB body | 11 ms | 3 ms | — |
-| 64 KB body | 11 ms | 2–4 ms | — |
-| 256 KB body | 7 ms | 3.4 ms | ~13 ms/MB |
-| 1 MB body | 11 ms | 6–12 ms | ~9 ms/MB |
-| 4 MB body | 31 ms | 21–35 ms | ~7 ms/MB |
-| **Same 16 KB page over HTTP/2** | 12 ms | 2.2 ms | — |
-| **First request in a fresh isolate** | 46 ms | — | — |
-| **…after `warmup({ iterations: 5 })`** | 16 ms | — | — |
-
-One model fits every body-size row to within its spread:
-
-> **≈ 9.5 ms to open a connection + 2 ms per request + 5–8 ms per MB of body**
-
-The connection term recovered independently from each row lands between 5 and 11 ms, agreeing with
-the 9–12 ms measured for a new connection by other means. Most of it is the TLS handshake and
-certificate chain validation; almost none of it is parsing (see below).
+| | New connection (first request included) | Each further request, same connection |
+| --- | --- | --- |
+| 1 KB body | 6.4 ms | 1.6 ms |
+| 16 KB body | 6.5 ms | 1.7 ms |
+| 64 KB body | 6.7 ms | 1.9 ms |
+| 256 KB body | 7.4 ms | 2.6 ms |
+| 1 MB body | 10.4 ms | 5.6 ms |
+| 4 MB body | 22.4 ms | 17.6 ms |
+| **First request in a fresh isolate** | 46 ms | — |
+| **…after `warmup({ iterations: 5 })`** | 16 ms | — |
+
+Re-measured for 1.4.0 against a size-controlled origin through a proxy, ten rounds per size, HTTP/2
+negotiated, gzip on the wire. The rows are not independent measurements — they are one model, fitted
+to the sweep and then checked back against it:
+
+> **≈ 6.4 ms to open a connection + 1.6 ms per further request + ~4 ms per MB of body**
+
+Each sweep request fetches five pages — one on a fresh connection and four reusing it — so the two
+terms were separated by varying the reuse count rather than assumed: two pages against ten gives
+1.63 ms per further request, and the connection term falls out of the remainder. Fitted on 1 KB and
+4 MB, the model predicts 32.9 ms for the 1 MB row against 35 measured, and 92.9 for the 4 MB row
+against 94.
 
 The ranges are real, not imprecision: absolute CPU on this platform varies by up to ~1.5× between
 isolates and runs — the same sweep repeated lands on faster and slower machines — so the values are
@@ -609,6 +649,31 @@ excess above the warm floor without `warmup()`, 15 ms with it at five iterations
 1.1 ms per request respectively, amortised over an isolate's early life. Warming costs 10 ms of
 startup at one iteration and 22 ms at five, against a 1 s budget, and does not lower the warm floor.
 
+### What the optional switches cost
+
+Everything above is the default identity: curl's fingerprint, gzip and deflate, no post-quantum, no
+GREASE. Each switch below is off unless asked for, and the table is what asking costs. Measured on
+the edge the same way as the rest — differencing two work counts, minimum of samples.
+
+| Switch | Cost | Paid |
+|---|---|---|
+| `grease: true` | not measurable | a handful of extra bytes in one hello |
+| `tls.extensionOrder: 'shuffle'` | not measurable | shuffling ~11 items, once per handshake |
+| `headerOrder` | not measurable — the ordered list is *faster* than the platform `Headers` (1.6 µs against 3.8 µs) | per request |
+| `groups: { x25519mlkem768 }` | **+0.15 ms** with the bundled WASM, **+1.35 ms** with a pure-JS ML-KEM | per **connection**, not per request — amortised across every request that reuses it |
+| `ciphers: { chacha20 }` | **+2.0 ms/MB**, and only if the server *selects* it | per byte. Servers with AES hardware generally prefer AES-GCM, so the usual cost is zero and the offer is what matters |
+| `decoders: { br }` | **+4.4 ms/MB** | per byte, whenever an origin serves brotli. Harder compression is worse, not better: quality 11 is 16% smaller on the wire and 46% dearer to decode |
+| `profile: chrome` | the sum of the three above | |
+
+Two defaults moved in 1.4.0 and neither is visible in the table above them: matching curl's cipher
+order means AES-256-GCM is negotiated where AES-128-GCM used to be, measured at **+4%** per MB
+(1.50 against 1.45 ms/MB — hardware AES makes the extra rounds cheap), and the ordered header list
+replaced the platform `Headers`, which is slightly *cheaper*. Both are inside the ±1.5× spread the
+figures above already carry.
+
+Bundle: importing `tunnelfetch/profile/chrome` adds **~22 KB gzipped** for the two WASM primitives.
+Nothing else imports them, so a caller on the default identity carries none of it.
+
 ### What that costs in dollars
 
 Workers Standard bills $5/month including 10 million requests and 30 million CPU milliseconds, then

package/README.zh-CN.md

@@ -219,6 +219,26 @@ const client = new Client({ connect, proxy, decoders: { br: brotli } });
 
 brotli 本身落在原生 inflate 的 1.9 倍。这个差价就是这个编码的成本，而它省下的线上字节买不回来——见[这个包做不到什么](#这个包做不到什么为什么)。解码器名字会按 HTTP token 校验；解码器抛错时响应体 fail closed，而不是被截断；未注册的编码依然会被拒绝。
 
+### 一行 import 得到 Chrome 身份
+
+```js
+import { Client } from 'tunnelfetch';
+import { chrome } from 'tunnelfetch/profile/chrome';
+
+const client = new Client({ profile: chrome, connect, proxy, decoders: { br, zstd } });
+```
+
+这个子路径带着运行时没有原生实现的两个原语——`X25519MLKEM768` 密钥交换要的 ML-KEM-768,以及记录层要的 ChaCha20-Poly1305,都编译成无依赖的 WASM,并且都在本仓库里有已知答案测试。**导入即 opt-in**:打包器只为走这条路径的代码拉入它们,默认身份一个字节都不背。
+
+`br` 和 `zstd` 仍然要你自己带。它们不是密码学、没有唯一正解,所以 profile 会一直拒绝到你提供为止——**一个声称支持 br 却读不了的 Chrome,比一个老实说不支持的更糟**。
+
+不是「能构造出来」,是端到端验证过:
+
+| 源站 | | TLS | 群 | HTTP |
+|---|---|---|---|---|
+| `blog.cloudflare.com` | 200 | 1.3 | `0x11ec` X25519MLKEM768 | h2 |
+| `www.shopify.com` | 200 | 1.3 | `0x11ec` X25519MLKEM768 | h2 |
+
 ### HTTP/2 — 要的是访问，不是速度
 
 客户端默认在 ALPN 中同时报出 `h2` 与 `http/1.1`，服务器选中哪个就说哪个。没有单独的 API：
@@ -410,17 +430,22 @@ CertificateError [CERT_PIN_MISMATCH]: no certificate in the chain matches any co
 通过代理抓取一个尺寸可控的源站，热态，同一 isolate 上 7 轮以上取中位数，传输走 gzip。最后一列是同样的数字
 换算成速率，那是更值得随身记住的形式：
 
-| | 新连接 | 同一连接上的后续请求 | 边际速率 |
-| --- | --- | --- | --- |
-| 1 KB body | 11 ms | 2–3 ms | — |
-| 16 KB body | 11 ms | 3 ms | — |
-| 64 KB body | 11 ms | 2–4 ms | — |
-| 256 KB body | 7 ms | 3.4 ms | ~13 ms/MB |
-| 1 MB body | 11 ms | 6–12 ms | ~9 ms/MB |
-| 4 MB body | 31 ms | 21–35 ms | ~7 ms/MB |
-| **同一个 16 KB 页面走 HTTP/2** | 12 ms | 2.2 ms | — |
-| **全新 isolate 的第一个请求** | 46 ms | — | — |
-| **……调用 `warmup({ iterations: 5 })` 之后** | 16 ms | — | — |
+| | 新连接(含首个请求) | 同连接每次后续请求 |
+| --- | --- | --- |
+| 1 KB body | 6.4 ms | 1.6 ms |
+| 16 KB body | 6.5 ms | 1.7 ms |
+| 64 KB body | 6.7 ms | 1.9 ms |
+| 256 KB body | 7.4 ms | 2.6 ms |
+| 1 MB body | 10.4 ms | 5.6 ms |
+| 4 MB body | 22.4 ms | 17.6 ms |
+| **全新 isolate 的第一个请求** | 46 ms | — |
+| **…执行 `warmup({ iterations: 5 })` 之后** | 16 ms | — |
+
+为 1.4.0 重新测量:经代理打一个尺寸可控的源站,每个尺寸十轮,协商 HTTP/2,线上走 gzip。这些行**不是各自独立的测量**,而是一个模型拟合出来再回代验证的:
+
+> **≈ 开一条连接 6.4 ms + 每次后续请求 1.6 ms + 每 MB body 约 4 ms**
+
+每次扫描请求会抓五个页面——一个走新连接、四个复用它——所以两项是靠**改变复用次数**分离出来的,不是假设的:两页对十页得出每次后续请求 1.63 ms,连接项由余数得到。用 1 KB 和 4 MB 拟合,模型预测 1 MB 那行 32.9 ms(实测 35)、4 MB 那行 92.9 ms(实测 94)。
 
 有一个模型能把每一个尺寸行都拟合到它的散布之内：
 
@@ -517,6 +542,24 @@ inflate 本身（约 2 ms/MB）加上把 body 物化成 JS 字符串（约 1.7 m
 导入这个包是免费的。121 个内置锚是以主题 DN 哈希为索引的 base64 字符串，只有链实际落到的那一个会被解码，所以
 380 KB 打包（gzip 后 133 KB）的启动时间保持在约 2 ms，而一个导入了但没使用本包的请求是 0 ms。
 
+### 可选开关各自的成本
+
+上面所有数字都是默认身份:curl 指纹、gzip 与 deflate、无后量子、无 GREASE。下面每个开关默认都关着,这张表是「打开它要付什么」。测法与其余部分一致——差分两个工作量、取样本最小值。
+
+| 开关 | 成本 | 何时付 |
+|---|---|---|
+| `grease: true` | 测不出来 | 一次 hello 里多几个字节 |
+| `tls.extensionOrder: 'shuffle'` | 测不出来 | 每次握手洗牌约 11 个元素 |
+| `headerOrder` | 测不出来——有序列表比平台的 `Headers` **更快**(1.6 µs 对 3.8 µs) | 每请求 |
+| `groups: { x25519mlkem768 }` | 用内置 WASM **+0.15 ms**,用纯 JS 的 ML-KEM **+1.35 ms** | **每连接**,不是每请求——复用该连接的所有请求共同摊薄 |
+| `ciphers: { chacha20 }` | **+2.0 ms/MB**,而且只有服务器**选中**它时才付 | 每字节。有 AES 硬件加速的服务器通常偏好 AES-GCM,所以实际成本往往是零,真正起作用的是"出现在 offer 里" |
+| `decoders: { br }` | **+4.4 ms/MB** | 每字节,只要源站发 brotli。压得越狠越亏:quality 11 线上小 16%,解码贵 46% |
+| `profile: chrome` | 上面三项之和 | |
+
+1.4.0 里有两个默认值变了,而它们都没有出现在上面那张表里:套件顺序对齐 curl 之后,原本协商 AES-128-GCM 的地方现在协商 AES-256-GCM,实测**贵 4%**(1.50 对 1.45 ms/MB——硬件 AES 让多出来的轮次很便宜);有序 header 列表取代了平台 `Headers`,反而**略微更便宜**。两者都落在上面数字本来就带的 ±1.5× 波动之内。
+
+体积:`import 'tunnelfetch/profile/chrome'` 会为两个 WASM 原语增加约 **22 KB(gzip)**。没有其它地方引用它们,所以走默认身份的使用者一个字节都不背。
+
 ### 计划限制
 
 付费计划上 30 秒的默认 CPU 上限不是约束点——那大约是一次调用里 3000 条连接或 1 GB 的 body，而"同时等待响应头

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnelfetch",
-  "version": "1.2.0",
+  "version": "1.4.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",
@@ -51,6 +51,10 @@
     "./roots": {
       "types": "./types/trust/roots.d.ts",
       "default": "./src/trust/roots.js"
+    },
+    "./profile/chrome": {
+      "types": "./types/profile/chrome.d.ts",
+      "default": "./src/profile/chrome.js"
     }
   },
   "types": "./types/index.d.ts",

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';
@@ -81,7 +83,30 @@ const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
  *   yours and visible. Measured on the edge: WASM brotli decodes at about 2x native gzip, and
  *   the wire bytes it saves do not pay that back — see the README. The reason to turn it on is
  *   matching a browser's Accept-Encoding, not saving CPU.
+ * @property {{ chacha20?: import('./tls/aead.js').AeadOptions['impl'] }} [ciphers] injected AEAD
+ *   implementations, by capability name. `chacha20` (seal/open, RFC 8439) is what lets
+ *   TLS_CHACHA20_POLY1305_SHA256 be offered and performed — WebCrypto has no ChaCha20 on this
+ *   runtime, and a suite offered but not performable is a dead connection if a server selects it,
+ *   so without this the suite stays out of the ClientHello. Required by `profiles.chrome`.
+ * @property {{ x25519mlkem768?: import('./tls/hybrid.js').MlKem768 }} [groups] injected key-exchange
+ *   implementations, by capability name. `x25519mlkem768` (ML-KEM-768 keygen/encapsulate/
+ *   decapsulate) is what lets the post-quantum hybrid group be offered and performed; without it
+ *   the group stays out of the ClientHello. Required by `profiles.chrome`.
  * @property {boolean} [keepAlive] default true.
+ * @property {import('./profiles.js').FingerprintProfile} [profile] one coherent network identity
+ *   instead of a dozen knobs that can disagree — TLS, HTTP/2, header order and default headers
+ *   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 +131,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 +262,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 +279,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 = [];
@@ -382,7 +412,7 @@ async function openFreshAndSend(client, current, { hop, key, proxy, trust, tls }
       tls,
       alpn,
       resumption: resumptionFor(client, key),
-      deps: o.deps,
+      deps: tlsDeps(o),
       deadlines,
       limits: o.limits ?? {},
       now: o.now,
@@ -446,6 +476,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.
@@ -570,6 +606,22 @@ function serverNeverSawIt(err) {
   return err instanceof TunnelFetchError && err.code === codes.TLS_TRUNCATED && err.detail?.got === 0;
 }
 
+/**
+ * The TLS deps for a connection: the caller's injectable randomness/keygen, plus the injected
+ * crypto implementations (`ciphers` -> `aead`, `groups` -> `kem`) the TLS layer needs to offer and
+ * perform the capability-gated ChaCha20 suite and X25519MLKEM768 group. Folded in here rather than
+ * carried in `tls`, so they neither enter the pool key nor disable native-fetch delegation — they
+ * are injected primitives, not fingerprint configuration.
+ * @param {Readonly<import('./client.js').ClientOptions>} o
+ * @returns {import('./tls/connect.js').TlsDeps}
+ */
+function tlsDeps(o) {
+  const deps = { ...(o.deps ?? {}) };
+  if (o.ciphers) deps.aead = o.ciphers;
+  if (o.groups) deps.kem = o.groups;
+  return deps;
+}
+
 async function sendAndReceive(client, conn, current, { key, deadlines, reused }) {
   const o = client.options;
   const target = targetFromUrl(current.url);
@@ -611,7 +663,7 @@ async function sendAndReceive(client, conn, current, { key, deadlines, reused })
         trust: o.trust ?? { mode: 'system' },
         tls: o.tls ?? {},
         resumption: resumptionFor(client, key),
-        deps: o.deps,
+        deps: tlsDeps(o),
         deadlines,
         limits: o.limits ?? {},
         now: o.now,
@@ -723,11 +775,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 +803,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 +859,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 +900,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 };