tunnelfetch 1.2.0 → 1.4.0

package/types/profiles.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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: "chrome/150";
+    tls: Readonly<{
+        ciphers: readonly number[];
+        groups: readonly number[];
+        offerGroups: readonly number[];
+        sigSchemes: readonly number[];
+        alpn: string[];
+        extensionOrder: "shuffle";
+        grease: true;
+    }>;
+    http2Settings: readonly number[][];
+    http2ConnectionWindow: number;
+    http2PseudoHeaderOrder: readonly string[];
+    headerOrder: readonly string[];
+    headers: readonly string[][];
+    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/aead.d.ts

@@ -25,6 +25,12 @@ export function buildNonce(iv: Uint8Array, seq: number | bigint): Uint8Array;
  * @property {Uint8Array} key
  * @property {Uint8Array} iv the 12-byte static IV for TLS 1.3, the 4-byte implicit salt for
  *   TLS 1.2
+ * @property {{seal: (k: Uint8Array, n: Uint8Array, p: Uint8Array, aad: Uint8Array) => Uint8Array,
+ *             open: (k: Uint8Array, n: Uint8Array, c: Uint8Array, aad: Uint8Array) => Uint8Array | null}}
+ *   [impl] caller-supplied AEAD, required for ChaCha20-Poly1305 and unused otherwise. This runtime
+ *   has no WebCrypto ChaCha20 — its only native path is node:crypto, and taking it would cost the
+ *   package its "web platform only" property — so the implementation is injected. `open` returns
+ *   null when authentication fails.
  */
 /**
  * Create record protection for one direction under one key. A new key (handshake -> application,
@@ -33,7 +39,7 @@ export function buildNonce(iv: Uint8Array, seq: number | bigint): Uint8Array;
  * @param {AeadOptions} opts
  * @returns {Promise<Aead>}
  */
-export function createAead({ version, cipher, key, iv }: AeadOptions): Promise<Aead>;
+export function createAead({ version, cipher, key, iv, impl }: AeadOptions): Promise<Aead>;
 /**
  * Record protection for one direction under one key. `encrypt` returns the encrypted record
  * body ready for framing; `decrypt` either returns authenticated plaintext (with the inner
@@ -64,4 +70,14 @@ export type AeadOptions = {
      * TLS 1.2
      */
     iv: Uint8Array;
+    /**
+     * caller-supplied AEAD, required for ChaCha20-Poly1305 and unused otherwise. This runtime
+     * has no WebCrypto ChaCha20 — its only native path is node:crypto, and taking it would cost the
+     * package its "web platform only" property — so the implementation is injected. `open` returns
+     * null when authentication fails.
+     */
+    impl?: {
+        seal: (k: Uint8Array, n: Uint8Array, p: Uint8Array, aad: Uint8Array) => Uint8Array;
+        open: (k: Uint8Array, n: Uint8Array, c: Uint8Array, aad: Uint8Array) => Uint8Array | null;
+    } | undefined;
 };

package/types/tls/connect.d.ts

@@ -15,7 +15,12 @@
  *   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.
+ * @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
@@ -66,11 +71,19 @@
  * @property {object} peer
  */
 /**
- * Injectable nondeterminism. Supplying these makes a handshake byte-for-byte reproducible, which
- * is what allows a recorded session to be replayed in an offline test.
+ * Injectable nondeterminism and crypto primitives the platform does not provide.
+ *
+ * `randomBytes` and `generateKeyPair` supply reproducibility (a recorded session replayed in an
+ * offline test). `aead` and `kem` supply capabilities this runtime lacks entirely: ChaCha20 and
+ * ML-KEM are absent from WebCrypto here, so an implementation must be injected before the suite or
+ * group they back can be offered — a ClientHello being an offer a server may take.
  * @typedef {object} TlsDeps
  * @property {(n: number) => Uint8Array} [randomBytes]
  * @property {(algorithm: object, group: number) => Promise<CryptoKeyPair>} [generateKeyPair]
+ * @property {{ chacha20?: import('./aead.js').AeadOptions['impl'] }} [aead] injected AEAD
+ *   implementations by name; `chacha20` gates and performs TLS_CHACHA20_POLY1305_SHA256
+ * @property {{ x25519mlkem768?: import('./hybrid.js').MlKem768 }} [kem] injected KEM
+ *   implementations by name; `x25519mlkem768` gates and performs the X25519MLKEM768 hybrid group
  */
 /**
  * What a completed handshake reports about itself.
@@ -154,6 +167,14 @@ export type TlsOptions = {
      * 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
@@ -161,7 +182,7 @@ export type TlsOptions = {
      * 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;
+    extensionOrder?: number[] | "shuffle" | undefined;
     /**
      * fixed ClientHello.random, for reproducible handshakes.
      */
@@ -243,12 +264,30 @@ export type CapturedTicket = {
     peer: object;
 };
 /**
- * Injectable nondeterminism. Supplying these makes a handshake byte-for-byte reproducible, which
- * is what allows a recorded session to be replayed in an offline test.
+ * Injectable nondeterminism and crypto primitives the platform does not provide.
+ *
+ * `randomBytes` and `generateKeyPair` supply reproducibility (a recorded session replayed in an
+ * offline test). `aead` and `kem` supply capabilities this runtime lacks entirely: ChaCha20 and
+ * ML-KEM are absent from WebCrypto here, so an implementation must be injected before the suite or
+ * group they back can be offered — a ClientHello being an offer a server may take.
  */
 export type TlsDeps = {
     randomBytes?: ((n: number) => Uint8Array) | undefined;
     generateKeyPair?: ((algorithm: object, group: number) => Promise<CryptoKeyPair>) | undefined;
+    /**
+     * injected AEAD
+     * implementations by name; `chacha20` gates and performs TLS_CHACHA20_POLY1305_SHA256
+     */
+    aead?: {
+        chacha20?: import("./aead.js").AeadOptions["impl"];
+    } | undefined;
+    /**
+     * injected KEM
+     * implementations by name; `x25519mlkem768` gates and performs the X25519MLKEM768 hybrid group
+     */
+    kem?: {
+        x25519mlkem768?: import("./hybrid.js").MlKem768;
+    } | undefined;
 };
 /**
  * What a completed handshake reports about itself.

package/types/tls/constants.d.ts

@@ -67,6 +67,18 @@ export const CIPHER_NAME: {
 };
 /** Offered in ClientHello, in preference order. */
 export const TLS13_CIPHERS: number[];
+/**
+ * curl 8.21.0 / OpenSSL 3.6.3 offers its TLS 1.3 suites in this exact order — AES-256-GCM,
+ * ChaCha20-Poly1305, AES-128-GCM — captured off the wire 2026-08-01 (`0x1302 0x1303 0x1301`).
+ * ChaCha20 is SECOND, right after AES-256-GCM; that is "curl's position" for it.
+ *
+ * TLS13_CIPHERS above leads with AES-128, which is the order this package has always offered and
+ * which the offline test server keys its default suite selection off; reordering it would change
+ * the negotiated suite across the whole suite. So this curl-faithful order is used ONLY when a
+ * ChaCha20 implementation has been injected — i.e. when the caller has opted into being able to
+ * perform every suite curl offers — and never otherwise. See connect.js.
+ */
+export const TLS13_CIPHERS_WITH_CHACHA: number[];
 export const TLS12_CIPHERS: number[];
 /**
  * Per-suite parameters. `hash` drives the whole key schedule; `keyLen` the AEAD key size.
@@ -90,6 +102,7 @@ export namespace GROUP {
     let x25519: number;
     let x448: number;
     let ffdhe2048: number;
+    let x25519mlkem768: number;
 }
 export const GROUP_NAME: {
     [k: string]: string;
@@ -102,10 +115,14 @@ export const GROUP_NAME: {
 export const SUPPORTED_GROUPS: number[];
 /**
  * WebCrypto parameters per group, discriminated on `kind` because X25519 sizes its shared
- * secret in bytes while ECDH sizes it in bits.
+ * secret in bytes while ECDH sizes it in bits, and the ML-KEM hybrid is not a WebCrypto
+ * primitive at all — it carries wire sizes only, and hybrid.js owns the crypto.
  * @typedef {{ kind: 'x25519', algorithm: { name: string }, publicLen: number, secretLen: number }
  *   | { kind: 'ec', algorithm: { name: string, namedCurve: string }, publicLen: number,
- *       secretBits: number }} GroupParams
+ *       secretBits: number }
+ *   | { kind: 'hybrid', clientShareLen: number, serverShareLen: number, secretLen: number,
+ *       mlkemPublicLen: number, mlkemSecretKeyLen: number, mlkemCiphertextLen: number,
+ *       classicalPublicLen: number, classicalSecretLen: number }} GroupParams
  */
 /**
  * WebCrypto parameters per group. x448 and the finite-field groups are absent by design.
@@ -228,7 +245,8 @@ export type CipherParams = {
 };
 /**
  * WebCrypto parameters per group, discriminated on `kind` because X25519 sizes its shared
- * secret in bytes while ECDH sizes it in bits.
+ * secret in bytes while ECDH sizes it in bits, and the ML-KEM hybrid is not a WebCrypto
+ * primitive at all — it carries wire sizes only, and hybrid.js owns the crypto.
  */
 export type GroupParams = {
     kind: "x25519";
@@ -245,6 +263,16 @@ export type GroupParams = {
     };
     publicLen: number;
     secretBits: number;
+} | {
+    kind: "hybrid";
+    clientShareLen: number;
+    serverShareLen: number;
+    secretLen: number;
+    mlkemPublicLen: number;
+    mlkemSecretKeyLen: number;
+    mlkemCiphertextLen: number;
+    classicalPublicLen: number;
+    classicalSecretLen: number;
 };
 /**
  * How to verify one signature scheme with WebCrypto. `format: 'ecdsa-der'` marks the schemes

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

@@ -9,13 +9,14 @@
 /**
  * Generate an ephemeral key share for one group.
  * `generateKeyPair` is injectable so a recorded handshake can be replayed with the exact private
- * key that produced it.
+ * key that produced it. X25519MLKEM768 dispatches to hybrid.js, using the injected ML-KEM
+ * implementation from `deps.kem`.
  *
  * @param {number} group
  * @param {import('./connect.js').TlsDeps} [deps]
  * @returns {Promise<KeyShare>}
  */
-export function generateKeyShare(group: number, { generateKeyPair }?: import("./connect.js").TlsDeps): Promise<KeyShare>;
+export function generateKeyShare(group: number, deps?: import("./connect.js").TlsDeps): Promise<KeyShare>;
 /**
  * ECDH/X25519 shared secret. The peer's key is imported in raw form, which is where a malformed
  * point is caught: WebCrypto rejects a point that is not on the curve, so we do not have to
@@ -23,12 +24,15 @@ export function generateKeyShare(group: number, { generateKeyPair }?: import("./
  * so it is checked here first.
  *
  * @param {number} group
- * @param {CryptoKey} privateKey our ephemeral private key for the group
+ * @param {CryptoKey | import('./hybrid.js').HybridPrivate} privateKey our ephemeral private key
+ *   for the group (a compound value for the ML-KEM hybrid)
  * @param {Uint8Array} peerKey the server's raw public key from its key_share
+ * @param {import('./connect.js').TlsDeps} [deps] carries the injected ML-KEM implementation the
+ *   hybrid group needs; unused by the classical groups
  * @returns {Promise<Uint8Array>} throws on any degenerate or malformed peer key
  */
-export function deriveSharedSecret(group: number, privateKey: CryptoKey, peerKey: Uint8Array): Promise<Uint8Array>;
-export function buildClientHello({ hostname, keyShares, random, legacySessionId, ciphers, groups, sigSchemes, alpn, versions, extensionOrder, extraExtensions, psk, randomBytes, }: {
+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, }: {
     hostname: any;
     keyShares: any;
     random: any;
@@ -41,6 +45,7 @@ export function buildClientHello({ hostname, keyShares, random, legacySessionId,
     extensionOrder?: readonly number[] | undefined;
     extraExtensions?: never[] | undefined;
     psk?: null | undefined;
+    grease?: boolean | undefined;
     randomBytes?: ((n: any) => Uint8Array<any>) | undefined;
 }): {
     message: Uint8Array<ArrayBufferLike>;
@@ -351,6 +356,8 @@ export function checkAlpn(extensions: Map<number, Uint8Array>, offeredAlpn: stri
  * 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 };
 /**

package/types/tls/hybrid.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Generate a client key share for X25519MLKEM768.
+ *
+ * @param {MlKem768} kem the injected ML-KEM-768 implementation
+ * @param {import('./connect.js').TlsDeps} [deps] `generateKeyPair` is honoured for the X25519
+ *   half so a recorded handshake can be replayed with a fixed classical key
+ * @returns {Promise<{ group: number, keyExchange: Uint8Array, privateKey: HybridPrivate }>}
+ *   `keyExchange` is the 1216-byte wire share (ML-KEM encapsulation key || X25519 public key)
+ */
+export function generateHybridKeyShare(kem: MlKem768, { generateKeyPair }?: import("./connect.js").TlsDeps): Promise<{
+    group: number;
+    keyExchange: Uint8Array;
+    privateKey: HybridPrivate;
+}>;
+/**
+ * Derive the 64-byte hybrid shared secret from the server's X25519MLKEM768 key share.
+ *
+ * @param {MlKem768} kem the injected ML-KEM-768 implementation
+ * @param {HybridPrivate} privateKey what generateHybridKeyShare kept
+ * @param {Uint8Array} serverShare the server's 1120-byte key_exchange (ciphertext || X25519 pub)
+ * @returns {Promise<Uint8Array>} ML-KEM shared secret (32) || X25519 shared secret (32) = 64
+ */
+export function deriveHybridSecret(kem: MlKem768, privateKey: HybridPrivate, serverShare: Uint8Array): Promise<Uint8Array>;
+export const HYBRID_GROUP: number;
+/**
+ * An injected ML-KEM-768 implementation (FIPS 203). Shapes match `wasmcrypto`'s `mlkem768`:
+ */
+export type MlKem768 = {
+    /**
+     *   ML-KEM.KeyGen; `publicKey` is the 1184-byte encapsulation key, `secretKey` the 2400-byte
+     *   decapsulation key.
+     */
+    keygen: (seed?: Uint8Array) => {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+    /**
+     * ML-KEM.Encaps; used by a server, exercised by the offline test server.
+     */
+    encapsulate: (publicKey: Uint8Array) => {
+        cipherText: Uint8Array;
+        sharedSecret: Uint8Array;
+    };
+    /**
+     *   ML-KEM.Decaps; returns the 32-byte shared secret (implicit rejection on a bad ciphertext).
+     */
+    decapsulate: (cipherText: Uint8Array, secretKey: Uint8Array) => Uint8Array;
+};
+/**
+ * The private half kept between generateHybridKeyShare and deriveHybridSecret: the ML-KEM
+ * decapsulation key and the X25519 private key. Not a CryptoKey, so callers treat KeyShare's
+ * private component opaquely (they already do — it only ever flows back into derivation).
+ */
+export type HybridPrivate = {
+    /**
+     * the ML-KEM decapsulation key
+     */
+    mlkemSecretKey: Uint8Array;
+    /**
+     * the X25519 private key
+     */
+    classicalPrivateKey: CryptoKey;
+};

package/types/tls/record.d.ts

@@ -32,6 +32,10 @@
  *   record, TLS 1.3 only
  * @property {null | ((msg: HandshakeMessage) => void | Promise<void>)} [onPostHandshake]
  *   NewSessionTicket consumer; default is to discard
+ * @property {null | { chacha20?: import('./aead.js').AeadOptions['impl'] }} [aeadImpls] injected
+ *   AEAD implementations by name. ChaCha20-Poly1305 has no WebCrypto path on this runtime, so its
+ *   seal/open are supplied here and threaded into every createAead for the ChaCha20 suite (initial
+ *   keys and each KeyUpdate rotation). Absent for the AES-GCM-only default, which needs nothing.
  */
 export class RecordLayer {
     /**
@@ -46,6 +50,9 @@ export class RecordLayer {
     _shutdownGraceMs: number;
     _padding: ((type: number, length: number) => number) | null;
     _onPostHandshake: ((msg: HandshakeMessage) => void | Promise<void>) | null;
+    _aeadImpls: {
+        chacha20?: import("./aead.js").AeadOptions["impl"];
+    } | null;
     _version: number;
     /** @type {DirectionState} */
     _send: DirectionState;
@@ -124,6 +131,13 @@ export class RecordLayer {
         key?: Uint8Array;
         iv?: Uint8Array;
     }): Promise<NonNullable<DirectionState>>;
+    /**
+     * The injected AEAD implementation a suite needs, or null. Only ChaCha20-Poly1305 needs one on
+     * this runtime; every AES-GCM suite goes through WebCrypto and passes null.
+     * @param {number} cipher
+     * @returns {import('./aead.js').AeadOptions['impl'] | null}
+     */
+    _implFor(cipher: number): import("./aead.js").AeadOptions["impl"] | null;
     /**
      * Next handshake message during the handshake phase.
      * Returns `{ type, body, raw }` (raw includes the 4-byte header, ready for the transcript),
@@ -363,6 +377,15 @@ export type RecordLayerOptions = {
      * NewSessionTicket consumer; default is to discard
      */
     onPostHandshake?: ((msg: HandshakeMessage) => void | Promise<void>) | null | undefined;
+    /**
+     * injected
+     * AEAD implementations by name. ChaCha20-Poly1305 has no WebCrypto path on this runtime, so its
+     * seal/open are supplied here and threaded into every createAead for the ChaCha20 suite (initial
+     * keys and each KeyUpdate rotation). Absent for the AES-GCM-only default, which needs nothing.
+     */
+    aeadImpls?: {
+        chacha20?: import("./aead.js").AeadOptions["impl"];
+    } | null | undefined;
 };
 import { ByteReader } from '../util/bytes.js';
 import { ByteWriter } from '../util/bytes.js';