tunnelfetch 1.3.0 → 1.4.1

package/types/tls/connect.d.ts

@@ -71,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.
@@ -256,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/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,11 +24,14 @@ 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 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;

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';