tunnelfetch 1.9.0 → 1.12.0

package/types/tls/connect.d.ts

@@ -13,9 +13,23 @@
  * @property {number[]} [groups] supported_groups, in preference order.
  * @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. Every suite must be
- *   one this package can perform; an offer it cannot honour is a dead connection the moment a
- *   server selects it, so an unknown suite is refused here rather than on the wire.
+ * @property {number[]} [ciphers] cipher suites to offer, in preference order. By default every
+ *   suite must be one this package can perform: an offer it cannot honour is a dead connection the
+ *   moment a server selects it, so an unknown suite is refused here rather than on the wire.
+ * @property {number[]} [omitExtensions] extension types to leave out of the ClientHello, the
+ *   subtractive counterpart to `extraExtensions`. `status_request` (5) is the one extension this
+ *   package sends that curl does not, so an identity matching a sample without it needs this.
+ *   Dropping it gives up OCSP stapling, which is the only revocation signal this package can
+ *   consume — pairing it with `trust.revocation: 'require-staple'` is refused rather than left to
+ *   fail every connection.
+ * @property {boolean} [allowUnperformableCiphers] offer suites this package cannot complete.
+ *   For fingerprint fidelity only. Real clients offer far more than this package implements — curl
+ *   8.21.0 offers thirty against seven performable here, Chromium fifteen against seven — so a
+ *   hello restricted to what it can honour carries a cipher list shorter than any real client's,
+ *   which is exactly what a JA3 hash reads. With this set, a server that selects an unperformable
+ *   suite fails the handshake; the first such suite sits behind the TLS 1.3 ones in both real
+ *   lists, so a 1.3-capable server does not reach it. Knowingly trading a rare failure for an
+ *   accurate fingerprint is a legitimate choice; making it silently is not.
  * @property {Uint8Array[]} [extraExtensions] pre-encoded ClientHello extensions, appended before
  *   ordering. `extensionOrder` can only arrange extensions that were BUILT — it filters to what
  *   exists and sorts that — so ordering alone cannot produce an extension this package does not
@@ -169,11 +183,31 @@ export type TlsOptions = {
      */
     offerGroups?: number[] | undefined;
     /**
-     * cipher suites to offer, in preference order. Every suite must be
-     * one this package can perform; an offer it cannot honour is a dead connection the moment a
-     * server selects it, so an unknown suite is refused here rather than on the wire.
+     * cipher suites to offer, in preference order. By default every
+     * suite must be one this package can perform: an offer it cannot honour is a dead connection the
+     * moment a server selects it, so an unknown suite is refused here rather than on the wire.
      */
     ciphers?: number[] | undefined;
+    /**
+     * extension types to leave out of the ClientHello, the
+     * subtractive counterpart to `extraExtensions`. `status_request` (5) is the one extension this
+     * package sends that curl does not, so an identity matching a sample without it needs this.
+     * Dropping it gives up OCSP stapling, which is the only revocation signal this package can
+     * consume — pairing it with `trust.revocation: 'require-staple'` is refused rather than left to
+     * fail every connection.
+     */
+    omitExtensions?: number[] | undefined;
+    /**
+     * offer suites this package cannot complete.
+     * For fingerprint fidelity only. Real clients offer far more than this package implements — curl
+     * 8.21.0 offers thirty against seven performable here, Chromium fifteen against seven — so a
+     * hello restricted to what it can honour carries a cipher list shorter than any real client's,
+     * which is exactly what a JA3 hash reads. With this set, a server that selects an unperformable
+     * suite fails the handshake; the first such suite sits behind the TLS 1.3 ones in both real
+     * lists, so a 1.3-capable server does not reach it. Knowingly trading a rare failure for an
+     * accurate fingerprint is a legitimate choice; making it silently is not.
+     */
+    allowUnperformableCiphers?: boolean | undefined;
     /**
      * pre-encoded ClientHello extensions, appended before
      * ordering. `extensionOrder` can only arrange extensions that were BUILT — it filters to what

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

@@ -32,7 +32,7 @@ export function generateKeyShare(group: number, deps?: import("./connect.js").Tl
  * @returns {Promise<Uint8Array>} throws on any degenerate or malformed peer key
  */
 export function deriveSharedSecret(group: number, privateKey: CryptoKey | import("./hybrid.js").HybridPrivate, peerKey: Uint8Array, deps?: import("./connect.js").TlsDeps): Promise<Uint8Array>;
-export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extensionOrder, extraExtensions, psk, grease, randomBytes, }: {
+export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extensionOrder, extraExtensions, omitExtensions, psk, grease, randomBytes, }: {
     hostname: any;
     keyShares: any;
     random: any;
@@ -44,6 +44,7 @@ export function buildClientHello({ hostname, keyShares, random, legacySessionId,
     versions?: number[] | undefined;
     extensionOrder?: readonly number[] | undefined;
     extraExtensions?: never[] | undefined;
+    omitExtensions?: never[] | undefined;
     psk?: null | undefined;
     grease?: boolean | undefined;
     randomBytes?: ((n: any) => Uint8Array<any>) | undefined;
@@ -305,6 +306,7 @@ export function checkAlpn(extensions: Map<number, Uint8Array>, offeredAlpn: stri
  * @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 {number[]} [omitExtensions] extension types to leave out of the hello
  * @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
@@ -432,6 +434,10 @@ export type ClientHelloOptions = {
      * pre-encoded, sent verbatim (the HRR cookie)
      */
     extraExtensions?: Uint8Array<ArrayBufferLike>[] | undefined;
+    /**
+     * extension types to leave out of the hello
+     */
+    omitExtensions?: number[] | undefined;
     /**
      * 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

package/types/util/bytes.d.ts

@@ -74,21 +74,25 @@ export class UnexpectedEofError extends TunnelFetchError {
  * be retained beyond the caller's immediate use if memory matters.
  *
  * When the source is a byte stream — on the target runtime, a socket's readable is one — the
- * reader pulls with BYOB reads into large fresh views instead of taking the source's own
- * chunking. This is measured, not stylistic: the runtime delivers socket data in chunks of at
- * most 4096 bytes, ~1200 of them for a 4 MB body, and every chunk is a runtime/JS boundary
- * crossing; a BYOB read hands over everything the transport has buffered (up to the view size)
- * in one crossing, and resolves with a partial fill the instant anything at all is available,
- * so delivery latency is unchanged. Sources that are not byte streams (every in-process
+ * reader pulls with BYOB reads instead of taking the source's own chunking. This is measured, not
+ * stylistic: the runtime delivers socket data in chunks of at most 4096 bytes, ~1200 of them for a
+ * 4 MB body, and every chunk is a runtime/JS boundary crossing; a BYOB read collects several of
+ * them into one.
+ *
+ * How MANY it collects is the transport's decision, not the view's. A BYOB read resolves the
+ * instant any byte is available and never waits to fill, so the view is a ceiling that is normally
+ * not reached: measured over a 4 MB body, 37 KB average fill on a direct socket and 8 KB through a
+ * proxy, whatever the view size. Sizing the view far above that buys nothing and costs the
+ * allocation — see BYOB_PULL_BYTES. Sources that are not byte streams (every in-process
  * ReadableStream in this package and its tests) take the default-reader path unchanged.
  */
 export class ByteReader {
     /**
      * @param {ReadableStream<Uint8Array>} readable
-     * @param {number} [pullBytes] size of each BYOB view pulled from the source. Tunable because it
-     *   decides how many times a body crosses the runtime boundary on the way in, and that turned out
-     *   to be the largest single cost in a large response — 42 ms of a 106 ms 4 MB request is socket
-     *   reads and record decryption, of which the AEAD itself is under 2 ms.
+     * @param {number} [pullBytes] size of each BYOB view pulled from the source. Tunable because the
+     *   right value depends on how much the transport hands over per read, and that differs by a
+     *   factor of four between a direct socket and a proxied one — see BYOB_PULL_BYTES for the sweep.
+     *   Ignored on sources that are not byte streams, which take the default-reader path.
      */
     constructor(readable: ReadableStream<Uint8Array>, pullBytes?: number);
     _pullBytes: number;