tunnelfetch 1.1.2 → 1.3.0

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

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

package/types/client.d.ts

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

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

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

package/types/index.d.ts

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

package/types/profiles.d.ts

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

package/types/tls/connect.d.ts

@@ -14,6 +14,17 @@
  * @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 {boolean | number} [grease] send GREASE (RFC 8701) reserved values in the cipher list,
+ *   the extension list (one at each end), supported_groups, supported_versions and key_share.
+ *   Default false, because curl does not GREASE — Chromium does. A number is a seed, which makes
+ *   the hello reproducible; `true` draws one from `deps.randomBytes`. A server that negotiates a
+ *   GREASE value is refused with a typed error naming it.
+ * @property {number[] | 'shuffle'} [extensionOrder] ClientHello extension types, in the order to emit them.
+ *   JA3 and JA4 hash the extension list in WIRE ORDER, so this is most of what a fingerprinter
+ *   reads. Defaults to curl's order (`CURL_EXTENSION_ORDER`). Extensions not named keep their
+ *   natural position at the end; `pre_shared_key` is always last whatever is asked, because RFC
+ *   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 +155,26 @@ export type TlsOptions = {
      * cipher suites to offer, in preference order.
      */
     ciphers?: number[] | undefined;
+    /**
+     * signature_algorithms to offer, in preference order.
+     */
+    sigSchemes?: number[] | undefined;
+    /**
+     * send GREASE (RFC 8701) reserved values in the cipher list,
+     * the extension list (one at each end), supported_groups, supported_versions and key_share.
+     * Default false, because curl does not GREASE — Chromium does. A number is a seed, which makes
+     * the hello reproducible; `true` draws one from `deps.randomBytes`. A server that negotiates a
+     * GREASE value is refused with a typed error naming it.
+     */
+    grease?: number | boolean | undefined;
+    /**
+     * ClientHello extension types, in the order to emit them.
+     * JA3 and JA4 hash the extension list in WIRE ORDER, so this is most of what a fingerprinter
+     * 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[] | "shuffle" | undefined;
     /**
      * fixed ClientHello.random, for reproducible handshakes.
      */

package/types/tls/extensions.d.ts

@@ -1,3 +1,10 @@
+/**
+ * An extension of an arbitrary type with an arbitrary body. Exists for GREASE (RFC 8701), whose
+ * whole point is to carry a reserved type this package assigns no meaning to.
+ * @param {number} type
+ * @param {Uint8Array} body
+ */
+export function encodeRawExtension(type: number, body: Uint8Array): Uint8Array<ArrayBufferLike>;
 /**
  * server_name (RFC 6066). Only host_name (type 0) exists in practice.
  * An IP literal must NOT be sent as SNI — RFC 6066 s3 forbids it, and servers that do virtual

package/types/tls/grease.d.ts

@@ -0,0 +1,46 @@
+/** @param {number} v @returns {boolean} */
+export function isGrease(v: number): boolean;
+/**
+ * A deterministic-from-seed source of GREASE values and shuffles.
+ *
+ * Seeded rather than ad-hoc `Math.random` for two reasons: this package forbids ambient randomness
+ * in `src/` (repo-hygiene enforces it, so that every byte on the wire is reproducible in a test),
+ * and a fingerprint that cannot be reproduced cannot be asserted byte-for-byte.
+ *
+ * @param {number} seed
+ */
+export function greaseSource(seed: number): {
+    /** A GREASE value not yet handed out in this hello, since Chromium never repeats one. */
+    take(): number;
+    next: () => number;
+};
+/**
+ * Fisher-Yates over the middle of the extension list, leaving the ends alone.
+ *
+ * The first and last positions are not free: Chromium pins a GREASE extension to each, and
+ * `pre_shared_key` MUST be last of all (RFC 8446 s4.2.11 — the binder transcript is the hello
+ * truncated just before the binders, a range that only exists if nothing follows them). So the
+ * shuffle covers everything between the fixed ends and nothing else.
+ *
+ * @param {Array<Uint8Array>} parts encoded extensions, already ordered
+ * @param {{next: () => number}} rng
+ * @param {(e: Uint8Array) => number} typeOf
+ * @param {number} pskType
+ * @returns {Array<Uint8Array>}
+ */
+export function shuffleExtensions(parts: Array<Uint8Array>, rng: {
+    next: () => number;
+}, typeOf: (e: Uint8Array) => number, pskType: number): Array<Uint8Array>;
+/**
+ * A GREASE key_share entry: a reserved group with a single-byte key, which is what Chromium sends.
+ * The byte is fixed rather than random — it is never used for anything, and a value that varies
+ * would only make the hello harder to assert on.
+ *
+ * @param {number} group
+ */
+export function greaseKeyShare(group: number): {
+    group: number;
+    keyExchange: Uint8Array<ArrayBuffer>;
+};
+/** The sixteen reserved values (RFC 8701 s2): 0x0A0A, 0x1A1A, ... 0xFAFA. */
+export const GREASE_VALUES: readonly number[];

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

@@ -28,51 +28,31 @@ 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, grease, 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;
+    grease?: boolean | 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 +288,73 @@ 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.
+ */
+/** `extensionOrder: SHUFFLE_EXTENSIONS` reproduces what Chromium does — see grease.js. */
+export const SHUFFLE_EXTENSIONS: "shuffle";
+export const CURL_EXTENSION_ORDER: readonly number[];
 export { GROUP_PARAMS };
 /**
  * An ephemeral key share: the public half as sent in key_share, plus the private key the
@@ -324,6 +371,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 +474,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';