tunnelfetch 1.1.2 → 1.2.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.2.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.js

@@ -82,6 +82,11 @@ 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 {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
@@ -436,6 +441,11 @@ 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 } : {}),
       onClose: () => {
         client._h2conns.delete(h2);
         // Only drop the keyed entry if it is still this connection; a newer one may have replaced it.

package/src/http2/connection.js

@@ -117,6 +117,10 @@ 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 {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 +200,8 @@ 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;
     this._expectFirstSettings = true;
 
     this._fatal = null; // set once; rejects every stream and every future request
@@ -230,11 +236,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

package/src/tls/connect.js

@@ -135,6 +135,12 @@ function expectServerHello(msg, offers12) {
  * @property {number[]} [offerGroups] groups to send an actual key_share for. Default the first
  *   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.
+ *   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
+ *   8446 s4.2.11 defines the binder transcript as the hello truncated just before the binders.
  * @property {Uint8Array} [clientRandom] fixed ClientHello.random, for reproducible handshakes.
  * @property {Uint8Array} [legacySessionId] fixed legacy_session_id, likewise.
  * @property {boolean} [compatibilityCcs] send the middlebox-compatibility ChangeCipherSpec.
@@ -326,6 +332,8 @@ async function drive({ record, hostname, verifyPeer, options, deps, versions })
     alpn,
     ciphers,
     versions,
+    extensionOrder: options.extensionOrder,
+    sigSchemes: options.sigSchemes,
     random: options.clientRandom,
     legacySessionId: options.legacySessionId,
     psk: pskOffer && {

package/src/tls/handshake-messages.js

@@ -210,6 +210,65 @@ export async function deriveSharedSecret(group, privateKey, peerKey) {
  * @param {ClientHelloOptions} opts
  * @returns {ClientHello}
  */
+/**
+ * Extension emission order, by type. This is not cosmetic: JA3 and JA4 hash the extension list in
+ * WIRE ORDER, so the order alone is a large part of what a fingerprinter reads.
+ *
+ * Captured from curl 8.21.0 / OpenSSL 3.6.3, which sends:
+ *   renegotiation_info, server_name, ec_point_formats, supported_groups, ALPN, encrypt_then_mac,
+ *   extended_master_secret, post_handshake_auth, signature_algorithms, supported_versions,
+ *   psk_key_exchange_modes, key_share
+ *
+ * Two of those this package does not send, and the reason is the same in both cases — an extension
+ * is a claim about what we can do. encrypt_then_mac only applies to CBC suites, which are not
+ * offered; post_handshake_auth invites a CertificateRequest after the handshake, which is not
+ * implemented. status_request goes the other way: curl does not send it, this package does,
+ * because a stapled OCSP response is its only revocation signal. It is placed where OpenSSL puts
+ * it when it does send one, right after server_name.
+ *
+ * Anything not named here keeps its natural position at the end, and pre_shared_key is forced last
+ * 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.
+ */
+export const CURL_EXTENSION_ORDER = Object.freeze([
+  EXTENSION.renegotiation_info,
+  EXTENSION.server_name,
+  EXTENSION.status_request,
+  EXTENSION.ec_point_formats,
+  EXTENSION.supported_groups,
+  EXTENSION.alpn,
+  EXTENSION.extended_master_secret,
+  EXTENSION.signature_algorithms,
+  EXTENSION.supported_versions,
+  EXTENSION.psk_key_exchange_modes,
+  EXTENSION.key_share,
+]);
+
+/**
+ * Put the encoded extensions into the requested order.
+ *
+ * @param {Array<Uint8Array|null>} parts encoded extensions, nulls for the ones not offered
+ * @param {number[]} order extension types, most significant first
+ * @returns {Array<Uint8Array>}
+ */
+function orderExtensions(parts, order) {
+  const present = parts.filter(Boolean);
+  const typeOf = (e) => (e[0] << 8) | e[1];
+  // pre_shared_key is not the caller's to place.
+  const psk = present.filter((e) => typeOf(e) === EXTENSION.pre_shared_key);
+  const rest = present.filter((e) => typeOf(e) !== EXTENSION.pre_shared_key);
+  const rank = new Map(order.map((t, i) => [t, i]));
+  // A stable sort on rank, with unranked extensions after every ranked one in the order they were
+  // built. Array.prototype.sort is required to be stable, so equal ranks keep their relative order.
+  return [
+    ...rest
+      .map((e, i) => ({ e, i, r: rank.get(typeOf(e)) ?? Number.MAX_SAFE_INTEGER }))
+      .sort((x, y) => x.r - y.r || x.i - y.i)
+      .map((x) => x.e),
+    ...psk,
+  ];
+}
+
 export function buildClientHello({
   hostname,
   keyShares,
@@ -220,6 +279,7 @@ export function buildClientHello({
   sigSchemes = SUPPORTED_SIG_SCHEMES,
   alpn = [ALPN_HTTP11],
   versions = [TLS13, TLS12],
+  extensionOrder = CURL_EXTENSION_ORDER,
   extraExtensions = [],
   psk = null,
   randomBytes = defaultRandom,
@@ -285,7 +345,7 @@ export function buildClientHello({
     .vector(1, sessionId)
     .vector(2, suiteBytes.build())
     .vector(1, Uint8Array.from([0])) // legacy_compression_methods: null only
-    .push(encodeExtensionBlock(extensionParts))
+    .push(encodeExtensionBlock(orderExtensions(extensionParts, extensionOrder)))
     .build();
 
   const message = handshakeMessage(HANDSHAKE_TYPE.client_hello, body);

package/src/tls/handshake.js

@@ -239,6 +239,10 @@ export async function continueTls13(ctx) {
       alpn,
       ciphers,
       versions,
+      // The retry must reproduce the first hello's extension set AND order: s4.1.2 does not list
+      // either among the modifications a second ClientHello may make, and a strict server checks.
+      extensionOrder: options.extensionOrder,
+      sigSchemes: options.sigSchemes,
       random: hello.clientRandom,
       legacySessionId: hello.legacySessionId,
       extraExtensions: cookie ? [cookieExtension(cookie)] : [],

package/src/warmup-fixture.js

@@ -18,61 +18,61 @@ export const WARMUP_HOSTNAME = "warmup.invalid";
 export const WARMUP_NOW = 1893456000000; // fixed epoch ms inside the chain's validity window
 
 const CLIENT_PRIV =
-  "MC4CAQAwBQYDK2VuBCIEIPjlXa5xRQTO0OmW85dWmeM6C0AjCqfOKH5MJlnIpT9b";
+  "MC4CAQAwBQYDK2VuBCIEINivgNQO5n8jwnzWfEWjdR14q7Km+UhPnqyL3RtkDbF7";
 const CLIENT_PUB =
-  "vbmT3r0piIyf5GavMXh1RqIsCml4dFibAAgovDW+Vww=";
+  "o5wNrq9yxfTLf8U3jLhUsXB52Kmf2q3zodyy/4jELSM=";
 const CLIENT_RANDOM =
   "AwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dw=";
 const SESSION_ID =
   "BRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1o=";
 const CLIENT_HELLO =
   "AQAA9AMDAwoRGB8mLTQ7QklQV15lbHN6gYiPlp2kq7K5wMfO1dwgBRAbJjE8R1JdaHN+iZSfqrXAy9bh7PcCDRgjLjlET1oADBMB" +
-  "EwLAK8AvwCzAMAEAAJ8AAAATABEAAA53YXJtdXAuaW52YWxpZAAFAAUBAAAAAAAKAAoACAAdABcAGAAZAA0AFgAUBAMFAwYDCAQI" +
-  "BQgGCAcEAQUBBgEAEAALAAkIaHR0cC8xLjEAKwAFBAMEAwMAMwAmACQAHQAgvbmT3r0piIyf5GavMXh1RqIsCml4dFibAAgovDW+" +
-  "VwwALQACAQEAFwAAAAsAAgEA/wEAAQA=";
+  "EwLAK8AvwCzAMAEAAJ//AQABAAAAABMAEQAADndhcm11cC5pbnZhbGlkAAUABQEAAAAAAAsAAgEAAAoACgAIAB0AFwAYABkAEAAL" +
+  "AAkIaHR0cC8xLjEAFwAAAA0AFgAUBAMFAwYDCAQIBQgGCAcEAQUBBgEAKwAFBAMEAwMALQACAQEAMwAmACQAHQAgo5wNrq9yxfTL" +
+  "f8U3jLhUsXB52Kmf2q3zodyy/4jELSM=";
 const SERVER_BYTES =
-  "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";
+  "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";
 const ROOT_DER =
   "MIIC2jCCAcKgAwIBAgIBATANBgkqhkiG9w0BAQsFADAeMRwwGgYDVQQDDBNXYXJtdXAgRml4dHVyZSBSb290MB4XDTI1MDEwMTAw" +
   "MDAwMFoXDTM1MDEwMTAwMDAwMFowHjEcMBoGA1UEAwwTV2FybXVwIEZpeHR1cmUgUm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEP" +
-  "ADCCAQoCggEBAMlyqJWB5tdme7o+TptR4T2er2MD5gsVcRmg1XWAIHnjY5Wy+cQ9dn670JtY5My0WBX+RSDPFsRzPnimzyLm2Jzs" +
-  "J8xpOMDtfE3/NUjxLSHrhdxJ+gFqoB0j7faIzLar1EXMdlhGCmFtXXoMQyuKhlMRzqP3VpH0N91OkGueQFlJAsuazEf9zm0v6PnV" +
-  "1QuH4X4+/wRYeAjrLmksLkLhI2h/QZ/EwiVwcLQUvPb4kSHeemZKRRXByLAqOBj6g/MqFRkhqiYQmDB4upjBcYHC8Ae9b02hP8vQ" +
-  "q9Dv5pRGloGk7olcviiSTj3YTIFd5Cd7xQZXyE42dJa6C9bZHkgZHPMCAwEAAaMjMCEwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8B" +
-  "Af8EBAMCAgQwDQYJKoZIhvcNAQELBQADggEBAB62L1/vofc1iZN1EoyIdHfgQZS7EtrjO4kkpHJPb2e1AmgvSCGSBC1OBaqlgpcT" +
-  "gSfmwSY7g059w18gaEkBhjm5czUmt+IM1DWir6hLPI//6QizsQo0AatePnMvJYuny9VMG2HWbpY17IKxT3/sG4zID7XtDjycuBkf" +
-  "uy6DN6Qrp0+aqYMfXs28HWwDgf3b7ZjEAwquSQ+dG8Ml36fd8hjydf2VjOl0h5C3xfc88sEEv0BAks11cYjHDT6jHNYYbXfWcesk" +
-  "nflRe2my0pLsKJFzVhQvpWl6Tud5+Im99hi0GMI1L17hMv9YlCGR+vIQsP78y/WTIEHMiFTpCWd1NTY=";
+  "ADCCAQoCggEBAMEAjrxVUntvHweCVz7mjYZTWZiTOW3mabXocCrFXKs8CcJVYNGQkpvhC/1VIr4t7hdrSPG31j6PvR4x0OAZTJZR" +
+  "k++Zo1jPUWIG3YomFJWhVjoJqoZTcO8uMDydvO75OTxto6Mc5gpfzHgfc52aAqemSqnfzryjupS6o1KOwbE1byLjM/Mmpp4CrRXx" +
+  "Fy/Jd8g2w1dSTTZo7QDIYBuZcNW4UYna9Mpac7otnv8JdlRSKonbbxXbx1E2GUm0tVM+4B5ARtBOFggnZYNW+KvQwcl4NRLTrFZS" +
+  "KNaRAW78DxclmSBsMm0lV+lsnV9miyuR2vfsj1FwSHKe1gzf12yRMpECAwEAAaMjMCEwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8B" +
+  "Af8EBAMCAgQwDQYJKoZIhvcNAQELBQADggEBAGmB1ws+kKHGtO5D8UnCCyXI/q5LtHsMDO+lDwp/6HAKJ6xVnJCNVP4d1/nTwMVm" +
+  "KeJTfEseakqaVSiUcowlPEgSM1OVIRU6aRqBog4cjyBt9F74cmdy+VOewkd4jwHUDnkuj8sNx6BdU8FN83w2nIlQ35g/exzQDP8q" +
+  "mB/GtQlnGbmi6mRMKzFn5stSwQS5tcTwz8h5dkDG2FtsBG4f8YDs8r2G0ur7FQD9aIhlttcUUdSE1mZHm4itgqgyE+hreL0x0wqz" +
+  "7V7NQK7fMH8OLTr5JrjVMyrpX8EQqyntEkAS8IaaQ42h3GNo1+HRVeJ9M53noaveacxhtTZDnI5u8wA=";
 
 export const WARMUP_FIXTURE = {
   clientPrivPkcs8: () => B(CLIENT_PRIV),

package/types/client.d.ts

@@ -65,6 +65,11 @@ 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 {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
@@ -222,6 +227,14 @@ export type ClientOptions = {
      * default true.
      */
     keepAlive?: boolean | 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
+     * 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`).
+     */
+    http2Settings?: [number, number][] | undefined;
     /**
      * 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

package/types/http2/connection.d.ts

@@ -74,6 +74,8 @@ export class Http2Connection {
         endStream: boolean;
     } | null;
     _maxHeaderBlockBytes: number;
+    /** @type {Array<[number, number]> | null} the SETTINGS flight, ids and order included */
+    _settingsFlight: Array<[number, number]> | null;
     _expectFirstSettings: boolean;
     _fatal: any;
     _goaway: {
@@ -252,6 +254,13 @@ export type Http2ConnectionOptions = {
      * self-protection cap on a decoded response header list.
      */
     maxHeaderListSize?: number | undefined;
+    /**
+     * 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.
+     */
+    settings?: [number, number][] | undefined;
     /**
      * 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

package/types/tls/connect.d.ts

@@ -14,6 +14,12 @@
  * @property {number[]} [offerGroups] groups to send an actual key_share for. Default the first
  *   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.
+ *   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
+ *   8446 s4.2.11 defines the binder transcript as the hello truncated just before the binders.
  * @property {Uint8Array} [clientRandom] fixed ClientHello.random, for reproducible handshakes.
  * @property {Uint8Array} [legacySessionId] fixed legacy_session_id, likewise.
  * @property {boolean} [compatibilityCcs] send the middlebox-compatibility ChangeCipherSpec.
@@ -144,6 +150,18 @@ export type TlsOptions = {
      * cipher suites to offer, in preference order.
      */
     ciphers?: number[] | undefined;
+    /**
+     * signature_algorithms to offer, in preference order.
+     */
+    sigSchemes?: number[] | 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
+     * 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
+     * 8446 s4.2.11 defines the binder transcript as the hello truncated just before the binders.
+     */
+    extensionOrder?: number[] | undefined;
     /**
      * fixed ClientHello.random, for reproducible handshakes.
      */

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

@@ -28,51 +28,30 @@ 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>;
-/**
- * @typedef {object} ClientHelloOptions
- * @property {string} hostname SNI, unless it is an IP literal (then no SNI is sent)
- * @property {Array<{ group: number, keyExchange: Uint8Array }>} keyShares public halves to
- *   offer; empty for a 1.2-only hello, whose wire form must not carry the extension at all
- * @property {Uint8Array} [random] fixed ClientHello.random, for reproducible handshakes
- * @property {Uint8Array} [legacySessionId] fixed legacy_session_id, likewise
- * @property {number[]} [ciphers] default: the union for the offered versions, 1.3 first
- * @property {number[]} [groups] supported_groups, default SUPPORTED_GROUPS
- * @property {number[]} [sigSchemes] default SUPPORTED_SIG_SCHEMES
- * @property {string[]} [alpn] default ['http/1.1']; empty array omits the extension
- * @property {number[]} [versions] default [TLS13, TLS12]
- * @property {Uint8Array[]} [extraExtensions] pre-encoded, sent verbatim (the HRR cookie)
- * @property {{ identity: Uint8Array, obfuscatedTicketAge: number, binderLen: number }} [psk]
- *   offer this resumption PSK. Encoded with a zeroed binder placeholder; the caller MUST derive
- *   the real binder over `message.subarray(0, truncatedLength)` and patch it in at
- *   `binderOffset` before the hello touches the wire — a zero binder on the wire is a hello
- *   every honest server must reject.
- * @property {(n: number) => Uint8Array} [randomBytes] injectable randomness
- */
-/**
- * The built hello plus everything later steps need to police the server's answer against what
- * was actually offered — negotiation checks must run against this record, never against the
- * defaults they might have come from.
- * @typedef {object} ClientHello
- * @property {Uint8Array} message framed handshake message, ready for the record layer
- * @property {Uint8Array} clientRandom
- * @property {Uint8Array} legacySessionId
- * @property {number[]} offeredCiphers
- * @property {number[]} offeredGroups
- * @property {number[]} offeredSigSchemes
- * @property {Set<number>} offeredExtensions extension types present in the hello
- * @property {string[]} offeredAlpn
- * @property {number} [binderOffset] psk only: where the binder's bytes sit in `message`
- * @property {number} [truncatedLength] psk only: how many leading bytes of `message` the binder
- *   transcript covers (RFC 8446 s4.2.11.2 truncation — everything except the binders list)
- */
-/**
- * Build a ClientHello. Returns the framed handshake message plus the metadata the rest of the
- * handshake needs to police the server's answer.
- *
- * @param {ClientHelloOptions} opts
- * @returns {ClientHello}
- */
-export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extraExtensions, psk, randomBytes, }: ClientHelloOptions): ClientHello;
+export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extensionOrder, extraExtensions, psk, randomBytes, }: {
+    hostname: any;
+    keyShares: any;
+    random: any;
+    legacySessionId: any;
+    ciphers: any;
+    groups?: number[] | undefined;
+    sigSchemes?: number[] | undefined;
+    alpn?: string[] | undefined;
+    versions?: number[] | undefined;
+    extensionOrder?: readonly number[] | undefined;
+    extraExtensions?: never[] | undefined;
+    psk?: null | undefined;
+    randomBytes?: ((n: any) => Uint8Array<any>) | undefined;
+}): {
+    message: Uint8Array<ArrayBufferLike>;
+    clientRandom: any;
+    legacySessionId: any;
+    offeredCiphers: any;
+    offeredGroups: number[];
+    offeredSigSchemes: number[];
+    offeredExtensions: Set<any>;
+    offeredAlpn: string[];
+};
 /**
  * Patch the real binder over the placeholder `buildClientHello` emitted. Separate from the
  * builder because the binder is derived FROM the built message (truncated), so there is no
@@ -308,6 +287,71 @@ export function checkFinished(received: Uint8Array, expected: Uint8Array): true;
  * @returns {string | null} null when the server declined ALPN entirely
  */
 export function checkAlpn(extensions: Map<number, Uint8Array>, offeredAlpn: string[], where: string): string | null;
+/**
+ * @typedef {object} ClientHelloOptions
+ * @property {string} hostname SNI, unless it is an IP literal (then no SNI is sent)
+ * @property {Array<{ group: number, keyExchange: Uint8Array }>} keyShares public halves to
+ *   offer; empty for a 1.2-only hello, whose wire form must not carry the extension at all
+ * @property {Uint8Array} [random] fixed ClientHello.random, for reproducible handshakes
+ * @property {Uint8Array} [legacySessionId] fixed legacy_session_id, likewise
+ * @property {number[]} [ciphers] default: the union for the offered versions, 1.3 first
+ * @property {number[]} [groups] supported_groups, default SUPPORTED_GROUPS
+ * @property {number[]} [sigSchemes] default SUPPORTED_SIG_SCHEMES
+ * @property {string[]} [alpn] default ['http/1.1']; empty array omits the extension
+ * @property {number[]} [versions] default [TLS13, TLS12]
+ * @property {Uint8Array[]} [extraExtensions] pre-encoded, sent verbatim (the HRR cookie)
+ * @property {{ identity: Uint8Array, obfuscatedTicketAge: number, binderLen: number }} [psk]
+ *   offer this resumption PSK. Encoded with a zeroed binder placeholder; the caller MUST derive
+ *   the real binder over `message.subarray(0, truncatedLength)` and patch it in at
+ *   `binderOffset` before the hello touches the wire — a zero binder on the wire is a hello
+ *   every honest server must reject.
+ * @property {(n: number) => Uint8Array} [randomBytes] injectable randomness
+ */
+/**
+ * The built hello plus everything later steps need to police the server's answer against what
+ * was actually offered — negotiation checks must run against this record, never against the
+ * defaults they might have come from.
+ * @typedef {object} ClientHello
+ * @property {Uint8Array} message framed handshake message, ready for the record layer
+ * @property {Uint8Array} clientRandom
+ * @property {Uint8Array} legacySessionId
+ * @property {number[]} offeredCiphers
+ * @property {number[]} offeredGroups
+ * @property {number[]} offeredSigSchemes
+ * @property {Set<number>} offeredExtensions extension types present in the hello
+ * @property {string[]} offeredAlpn
+ * @property {number} [binderOffset] psk only: where the binder's bytes sit in `message`
+ * @property {number} [truncatedLength] psk only: how many leading bytes of `message` the binder
+ *   transcript covers (RFC 8446 s4.2.11.2 truncation — everything except the binders list)
+ */
+/**
+ * Build a ClientHello. Returns the framed handshake message plus the metadata the rest of the
+ * handshake needs to police the server's answer.
+ *
+ * @param {ClientHelloOptions} opts
+ * @returns {ClientHello}
+ */
+/**
+ * Extension emission order, by type. This is not cosmetic: JA3 and JA4 hash the extension list in
+ * WIRE ORDER, so the order alone is a large part of what a fingerprinter reads.
+ *
+ * Captured from curl 8.21.0 / OpenSSL 3.6.3, which sends:
+ *   renegotiation_info, server_name, ec_point_formats, supported_groups, ALPN, encrypt_then_mac,
+ *   extended_master_secret, post_handshake_auth, signature_algorithms, supported_versions,
+ *   psk_key_exchange_modes, key_share
+ *
+ * Two of those this package does not send, and the reason is the same in both cases — an extension
+ * is a claim about what we can do. encrypt_then_mac only applies to CBC suites, which are not
+ * offered; post_handshake_auth invites a CertificateRequest after the handshake, which is not
+ * implemented. status_request goes the other way: curl does not send it, this package does,
+ * because a stapled OCSP response is its only revocation signal. It is placed where OpenSSL puts
+ * it when it does send one, right after server_name.
+ *
+ * Anything not named here keeps its natural position at the end, and pre_shared_key is forced last
+ * 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.
+ */
+export const CURL_EXTENSION_ORDER: readonly number[];
 export { GROUP_PARAMS };
 /**
  * An ephemeral key share: the public half as sent in key_share, plus the private key the
@@ -324,6 +368,18 @@ export type KeyShare = {
      */
     privateKey: CryptoKey;
 };
+/**
+ * A parsed ServerHello. `isHelloRetryRequest` is decided by the random alone (RFC 8446 s4.1.3);
+ * everything else is exactly what the wire carried, judged later by the negotiate* functions.
+ */
+export type ServerHello = {
+    legacyVersion: number;
+    random: Uint8Array;
+    legacySessionIdEcho: Uint8Array;
+    cipherSuite: number;
+    extensions: Map<number, Uint8Array>;
+    isHelloRetryRequest: boolean;
+};
 export type ClientHelloOptions = {
     /**
      * SNI, unless it is an IP literal (then no SNI is sent)
@@ -415,16 +471,4 @@ export type ClientHello = {
      */
     truncatedLength?: number | undefined;
 };
-/**
- * A parsed ServerHello. `isHelloRetryRequest` is decided by the random alone (RFC 8446 s4.1.3);
- * everything else is exactly what the wire carried, judged later by the negotiate* functions.
- */
-export type ServerHello = {
-    legacyVersion: number;
-    random: Uint8Array;
-    legacySessionIdEcho: Uint8Array;
-    cipherSuite: number;
-    extensions: Map<number, Uint8Array>;
-    isHelloRetryRequest: boolean;
-};
 import { GROUP_PARAMS } from './constants.js';