tunnelfetch 1.0.0

package/src/tls/aead.js

@@ -0,0 +1,263 @@
+// AEAD record protection: nonce construction, inner-plaintext framing, both TLS versions.
+//
+// AES-GCM is the only AEAD here (see constants.js for why), driven through WebCrypto. The
+// runtime's AES-GCM rejects on tag mismatch rather than returning unauthenticated bytes, which
+// is what makes the fail-closed contract below possible: decrypt() either returns authenticated
+// plaintext or throws TLS_RECORD, never garbage.
+//
+// Sequence numbers are the caller's state (per direction, reset to zero on every key change —
+// record.js owns the counters), but their interpretation is fixed here:
+//
+//   TLS 1.3 (RFC 8446 s5.3): nonce = static_iv XOR seq, with seq left-padded to iv length.
+//   TLS 1.2 (RFC 5288):      nonce = 4-byte implicit salt || 8-byte explicit nonce; the
+//                            explicit part travels on the wire. We send seq as the explicit
+//                            nonce (the SHOULD of RFC 5288) but accept whatever the peer sent,
+//                            because the AAD — not the nonce — carries the implicit counter.
+//
+// Sequence numbers are 64-bit. They are handled as BigInt precisely because a Number-based
+// counter would silently lose precision past 2^53 and eventually reuse a nonce, which with GCM
+// forfeits both confidentiality and integrity. Reaching 2^64-1 throws instead of wrapping.
+
+import { TlsError, TlsUnsupportedError, codes, hex16 } from '../errors.js';
+import { concat, u8, u16 } from '../util/bytes.js';
+import {
+  CIPHER_PARAMS, CIPHER_NAME, MAX_PLAINTEXT, LEGACY_VERSION, TLS12, TLS13,
+} from './constants.js';
+
+const SEQ_MAX = (1n << 64n) - 1n; // the value at which the counter must not be used
+
+/** @param {number | bigint} seq */
+function checkSeq(seq) {
+  const s = typeof seq === 'bigint' ? seq : BigInt(seq);
+  if (s < 0n) throw new TlsError(codes.CONFIG_INVALID, `negative sequence number ${s}`);
+  if (s >= SEQ_MAX) {
+    // One shy of the full space: at 2^64-1 the *next* record would wrap to nonce 0. Refusing
+    // the last value makes "increment then check" ordering bugs unable to reuse a nonce.
+    throw new TlsError(codes.TLS_RECORD,
+      'record sequence number reached 2^64-1; the connection must rekey, not wrap',
+      { seq: s.toString() });
+  }
+  return s;
+}
+
+/**
+ * TLS 1.3 per-record nonce: the 64-bit sequence number left-padded to the IV length, XORed
+ * with the static IV. Exported so the tests can pin the construction independently of a full
+ * encrypt round trip.
+ * @param {Uint8Array} iv
+ * @param {number | bigint} seq
+ * @returns {Uint8Array}
+ */
+export function buildNonce(iv, seq) {
+  let s = checkSeq(seq);
+  const nonce = iv.slice();
+  for (let i = nonce.byteLength - 1; i >= nonce.byteLength - 8 && i >= 0; i--) {
+    nonce[i] ^= Number(s & 0xffn);
+    s >>= 8n;
+  }
+  return nonce;
+}
+
+/** The 64-bit sequence number as 8 big-endian bytes (TLS 1.2 explicit nonce and AAD). */
+function seq64(seq) {
+  let s = checkSeq(seq);
+  const out = new Uint8Array(8);
+  for (let i = 7; i >= 0; i--) {
+    out[i] = Number(s & 0xffn);
+    s >>= 8n;
+  }
+  return out;
+}
+
+/**
+ * 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
+ * content type under 1.3, the header type under 1.2) or throws TLS_RECORD — never garbage.
+ * @typedef {object} Aead
+ * @property {number} version
+ * @property {(seq: number | bigint, type: number, plaintext: Uint8Array,
+ *   opts?: { padding?: number }) => Promise<Uint8Array>} encrypt
+ * @property {(seq: number | bigint, body: Uint8Array, header: Uint8Array)
+ *   => Promise<{ type: number, plaintext: Uint8Array }>} decrypt
+ */
+
+/**
+ * @typedef {object} AeadOptions
+ * @property {number} [version] `TLS13` (default) or `TLS12`; picks nonce and AAD construction
+ * @property {number} cipher cipher suite id, must have CIPHER_PARAMS
+ * @property {Uint8Array} key
+ * @property {Uint8Array} iv the 12-byte static IV for TLS 1.3, the 4-byte implicit salt for
+ *   TLS 1.2
+ */
+
+/**
+ * Create record protection for one direction under one key. A new key (handshake -> application,
+ * KeyUpdate) means a new instance; sequence numbers restart with it.
+ *
+ * @param {AeadOptions} opts
+ * @returns {Promise<Aead>}
+ */
+export async function createAead({ version = TLS13, cipher, key, iv }) {
+  const params = CIPHER_PARAMS[cipher];
+  if (!params || params.hash === undefined) {
+    throw new TlsUnsupportedError(codes.TLS_CIPHER_UNSUPPORTED,
+      `cipher suite ${hex16(cipher)} (${CIPHER_NAME[cipher] ?? 'unknown'}) has no AEAD parameters`,
+      { cipher });
+  }
+  if (version !== TLS12 && version !== TLS13) {
+    throw new TlsError(codes.CONFIG_INVALID, `AEAD version ${hex16(version)} is not TLS 1.2/1.3`,
+      { version });
+  }
+  const { keyLen, ivLen, tagLen, fixedIvLen } = params;
+  const wantIv = version === TLS13 ? ivLen : fixedIvLen;
+  if (key.byteLength !== keyLen) {
+    throw new TlsError(codes.CONFIG_INVALID,
+      `key is ${key.byteLength} bytes; ${CIPHER_NAME[cipher]} needs ${keyLen}`, { cipher });
+  }
+  if (iv.byteLength !== wantIv) {
+    throw new TlsError(codes.CONFIG_INVALID,
+      `iv is ${iv.byteLength} bytes; ${CIPHER_NAME[cipher]} needs ${wantIv} for this version`,
+      { cipher, version });
+  }
+  const gcmKey = await crypto.subtle.importKey('raw', key, { name: 'AES-GCM' }, false,
+    ['encrypt', 'decrypt']);
+  const staticIv = iv.slice(); // defensive copy: the caller may zero or reuse its buffer
+
+  const tagFailure = () => new TlsError(codes.TLS_RECORD,
+    'AEAD authentication failed: record tag or additional data did not verify', {});
+
+  if (version === TLS13) {
+    return {
+      version,
+      /**
+       * Returns the encrypted record body (ciphertext + tag). The matching wire header is
+       * always `17 03 03 <len>`; the AAD here is built from the same rule, so a caller that
+       * frames differently will fail to interoperate rather than succeed unauthenticated.
+       */
+      async encrypt(seq, type, plaintext, { padding = 0 } = {}) {
+        if (!Number.isInteger(padding) || padding < 0) {
+          throw new TlsError(codes.CONFIG_INVALID,
+            `padding ${padding} is not a non-negative integer`);
+        }
+        if (plaintext.byteLength > MAX_PLAINTEXT) {
+          throw new TlsError(codes.CONFIG_INVALID,
+            `plaintext of ${plaintext.byteLength} bytes exceeds ${MAX_PLAINTEXT}; fragment first`,
+            { length: plaintext.byteLength });
+        }
+        // TLSInnerPlaintext = content || content_type || zero padding, capped at 2^14 + 1.
+        const room = MAX_PLAINTEXT - plaintext.byteLength;
+        const pad = Math.min(padding, room);
+        const inner = new Uint8Array(plaintext.byteLength + 1 + pad);
+        inner.set(plaintext, 0);
+        inner[plaintext.byteLength] = type;
+        const aad = concat([u8(23), u16(LEGACY_VERSION), u16(inner.byteLength + tagLen)]);
+        const nonce = buildNonce(staticIv, seq);
+        const ct = await crypto.subtle.encrypt(
+          { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
+          gcmKey, inner);
+        return new Uint8Array(ct);
+      },
+
+      /**
+       * @param {Uint8Array} body ciphertext + tag as read from the wire
+       * @param {Uint8Array} header the 5 record-header bytes — they ARE the AAD (RFC 8446 s5.2)
+       */
+      async decrypt(seq, body, header) {
+        if (header.byteLength !== 5) {
+          throw new TlsError(codes.CONFIG_INVALID,
+            `AAD must be the 5 header bytes, got ${header.byteLength}`);
+        }
+        // Minimum: tag plus one byte, because a valid inner plaintext holds at least the type.
+        if (body.byteLength < tagLen + 1) {
+          throw new TlsError(codes.TLS_RECORD,
+            `encrypted record body of ${body.byteLength} bytes is shorter than ` +
+            `tag+1 (${tagLen + 1})`,
+            { length: body.byteLength });
+        }
+        const nonce = buildNonce(staticIv, seq);
+        let inner;
+        try {
+          inner = new Uint8Array(await crypto.subtle.decrypt(
+            { name: 'AES-GCM', iv: nonce, additionalData: header, tagLength: tagLen * 8 },
+            gcmKey, body));
+        } catch {
+          throw tagFailure();
+        }
+        // Strip the zero padding to expose the real content type (RFC 8446 s5.4). Scanning
+        // from the end is not constant time, but padding length is not secret from an attacker
+        // who can measure it anyway via record timing; the RFC imposes no such requirement.
+        let i = inner.byteLength - 1;
+        while (i >= 0 && inner[i] === 0) i--;
+        if (i < 0) {
+          throw new TlsError(codes.TLS_RECORD,
+            'record plaintext is all padding with no content type byte', {});
+        }
+        const type = inner[i];
+        const plaintext = inner.subarray(0, i);
+        if (plaintext.byteLength > MAX_PLAINTEXT) {
+          throw new TlsError(codes.TLS_RECORD,
+            `record plaintext of ${plaintext.byteLength} bytes exceeds ${MAX_PLAINTEXT}`,
+            { length: plaintext.byteLength });
+        }
+        return { type, plaintext };
+      },
+    };
+  }
+
+  // ------------------------------------------------------------------ TLS 1.2 (RFC 5288)
+  return {
+    version,
+    /** Returns explicit_nonce(8) || ciphertext || tag — the GenericAEADCipher fragment. */
+    async encrypt(seq, type, plaintext, { padding = 0 } = {}) {
+      if (padding !== 0) {
+        // No inner-plaintext padding exists in 1.2; silently dropping the request would let a
+        // caller believe it is hiding lengths when it is not.
+        throw new TlsError(codes.CONFIG_INVALID, 'record padding is a TLS 1.3 feature', {});
+      }
+      if (plaintext.byteLength > MAX_PLAINTEXT) {
+        throw new TlsError(codes.CONFIG_INVALID,
+          `plaintext of ${plaintext.byteLength} bytes exceeds ${MAX_PLAINTEXT}; fragment first`,
+          { length: plaintext.byteLength });
+      }
+      const explicit = seq64(seq);
+      const nonce = concat([staticIv, explicit]);
+      const aad = concat([explicit, u8(type), u16(TLS12), u16(plaintext.byteLength)]);
+      const ct = new Uint8Array(await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
+        gcmKey, plaintext));
+      return concat([explicit, ct]);
+    },
+
+    /**
+     * The AAD is seq || type || version || plaintext-length (RFC 5246 s6.2.3.3). seq is OUR
+     * receive counter, not the peer's explicit nonce — that is what makes reordering and
+     * replay detectable. type/version are taken from the received header so the AAD binds
+     * exactly what the wire claimed.
+     */
+    async decrypt(seq, body, header) {
+      if (header.byteLength !== 5) {
+        throw new TlsError(codes.CONFIG_INVALID,
+          `header must be 5 bytes, got ${header.byteLength}`);
+      }
+      if (body.byteLength < 8 + tagLen) {
+        throw new TlsError(codes.TLS_RECORD,
+          `encrypted record body of ${body.byteLength} bytes is shorter than ` +
+          `nonce+tag (${8 + tagLen})`,
+          { length: body.byteLength });
+      }
+      const explicit = body.subarray(0, 8);
+      const nonce = concat([staticIv, explicit]);
+      const ptLen = body.byteLength - 8 - tagLen;
+      const aad = concat([seq64(seq), header.subarray(0, 3), u16(ptLen)]);
+      let plaintext;
+      try {
+        plaintext = new Uint8Array(await crypto.subtle.decrypt(
+          { name: 'AES-GCM', iv: nonce, additionalData: aad, tagLength: tagLen * 8 },
+          gcmKey, body.subarray(8)));
+      } catch {
+        throw tagFailure();
+      }
+      return { type: header[0], plaintext };
+    },
+  };
+}

package/src/tls/connect.js

@@ -0,0 +1,407 @@
+// TLS version negotiation: one ClientHello, one ServerHello, one dispatch.
+//
+// This is the entry point that offers TLS 1.3 and TLS 1.2 together, the way every real client
+// does: a single ClientHello carrying supported_versions [1.3, 1.2], both cipher-suite sets, a
+// key_share for 1.3, and the 1.2 compatibility extensions (extended_master_secret,
+// ec_point_formats, renegotiation_info). The server picks; we continue down the matching driver
+// on the SAME connection.
+//
+// What this file must never become is "try 1.3, and on failure reconnect at 1.2". That insecure
+// fallback dance is the one browsers tore out (POODLE was its harvest): an attacker who can
+// inject a TCP reset or a handshake_failure alert gets to choose the client's version. Here a
+// failure is a failure — there is no code path that dials again, at any version, for any reason.
+//
+// Offering 1.2 next to 1.3 is exactly the configuration RFC 8446's downgrade protections exist
+// for, and both run in this file's negotiation with the REAL offered list:
+//
+//   * the s4.1.3 sentinel in ServerHello.random — a 1.3-capable server pushed down to 1.2 by a
+//     stripped ClientHello brands its random, and negotiateVersion aborts on the brand;
+//   * the "selected version was not offered" check, which is what keeps 1.0/1.1 out entirely.
+//
+// The transcript rule from the drivers carries over unchanged and is the reason the preamble is
+// shaped the way it is: the transcript hash is chosen by the negotiated cipher suite, which is
+// only known from the ServerHello. So the ClientHello is held as raw bytes and the transcript is
+// constructed here exactly once, under the right hash — never started under a guess and rebuilt,
+// because rebuilding cannot reproduce the HelloRetryRequest substitution the 1.3 driver may have
+// to perform on it.
+
+import { TlsError, TlsUnsupportedError, codes, hex8 } from '../errors.js';
+import { RecordLayer } from './record.js';
+import { Transcript } from './transcript.js';
+import {
+  ALPN_HTTP11,
+  CIPHER_PARAMS,
+  HANDSHAKE_TYPE,
+  SUPPORTED_GROUPS,
+  TLS12,
+  TLS12_CIPHERS,
+  TLS13,
+  TLS13_CIPHERS,
+} from './constants.js';
+import {
+  buildClientHello,
+  generateKeyShare,
+  negotiateCipher,
+  negotiateVersion,
+  parseServerHello,
+  setPskBinder,
+} from './handshake-messages.js';
+import { describeVersion } from './extensions.js';
+import {
+  earlySecret,
+  finishedVerifyData,
+  hashLength,
+  resumptionBinderKey,
+} from './keyschedule.js';
+import { DEFAULT_OFFER_GROUPS, continueTls13 } from './handshake.js';
+import { continueTls12, refuseHelloRequest } from './handshake12.js';
+
+const DEFAULT_VERSIONS = [TLS13, TLS12];
+
+/**
+ * Validate and canonicalise the offer list. Newest first, always: supported_versions is a
+ * preference list, and there is no configuration in which preferring 1.2 while also offering
+ * 1.3 is anything but a downgrade written into the offer itself.
+ */
+function normalizeVersions(input) {
+  if (input === undefined) return DEFAULT_VERSIONS;
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new TlsError(
+      codes.CONFIG_INVALID,
+      'options.versions must be a non-empty array of TLS versions to offer',
+    );
+  }
+  const out = [];
+  for (const v of input) {
+    if (v !== TLS13 && v !== TLS12) {
+      throw new TlsUnsupportedError(
+        codes.TLS_VERSION_UNSUPPORTED,
+        `cannot offer ${describeVersion(v)}: only TLS 1.3 and TLS 1.2 are implemented. ` +
+          'TLS 1.0 and 1.1 have no AEAD cipher suites, and SSL is long dead.',
+        { version: v },
+      );
+    }
+    if (!out.includes(v)) out.push(v);
+  }
+  return out.sort((a, b) => b - a);
+}
+
+/**
+ * Demand that the first handshake message is a ServerHello. The one type refused BY NAME is
+ * HelloRequest, and only when 1.2 is on the table: a 1.2 server may legally emit one at any
+ * time, and the refusal must say "renegotiation" rather than "unknown type" (handshake12.js
+ * owns that stance and its wording).
+ */
+function expectServerHello(msg, offers12) {
+  if (msg === null) {
+    throw new TlsError(
+      codes.TLS_TRUNCATED,
+      'server closed the connection during the handshake while ServerHello was expected',
+      { expected: 'server_hello' },
+    );
+  }
+  if (msg.ccs) {
+    // In no version of TLS is a key change legal before the ServerHello; even 1.3's
+    // compatibility CCS is specified to follow the server's first handshake message.
+    throw new TlsError(codes.TLS_RECORD, 'change_cipher_spec arrived where ServerHello was expected', {
+      expected: 'server_hello',
+    });
+  }
+  if (offers12 && msg.type === 0) refuseHelloRequest(); // 0 = HelloRequest, deliberately unnamed
+  if (msg.type !== HANDSHAKE_TYPE.server_hello) {
+    throw new TlsError(
+      codes.TLS_HANDSHAKE,
+      `server sent handshake type ${hex8(msg.type)} where ServerHello was expected`,
+      { got: msg.type, expected: HANDSHAKE_TYPE.server_hello },
+    );
+  }
+  return msg;
+}
+
+/**
+ * A byte duplex: what every layer in this package consumes and produces.
+ * @typedef {{ readable: ReadableStream<Uint8Array>,
+ *             writable: WritableStream<Uint8Array> }} ByteDuplex
+ */
+
+/**
+ * Handshake knobs. Every one of these narrows what is offered; none can widen it beyond what
+ * `constants.js` permits, so no option here can talk the client into a suite it refuses.
+ *
+ * @typedef {object} TlsOptions
+ * @property {number[]} [versions] versions to offer, from `TLS13` / `TLS12`. Default both.
+ * @property {string[]} [alpn] ALPN protocols to offer. Default `['http/1.1']`.
+ * @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.
+ * @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.
+ *   Default true.
+ * @property {number} [maxHandshakeMessage] per-message cap; certificate chains dominate sizing.
+ * @property {number} [maxKeyUpdates] received KeyUpdates tolerated before it is called a flood.
+ * @property {number} [maxTranscriptBytes] cap on buffered handshake transcript.
+ * @property {ResumptionOffer} [psk] offer this resumption PSK (TLS 1.3 only; requires 1.3 in
+ *   the offered versions). The server may decline, in which case the full handshake continues
+ *   on this same connection — there is no reconnect at any layer.
+ * @property {(ticket: CapturedTicket) => void} [onSessionTicket] receive each NewSessionTicket
+ *   this connection yields, already reduced to a usable PSK per RFC 8446 s7.1. Without this the
+ *   tickets are read and discarded, exactly as before.
+ */
+
+/**
+ * A resumption PSK ready to offer, as produced by the ticket store from a CapturedTicket.
+ * `obfuscatedTicketAge` is a closure, not a number, because the age must be current at the
+ * moment each hello is BUILT — a HelloRetryRequest builds a second hello later — and because
+ * clock policy belongs to the store, not to this layer (which otherwise never reads a clock).
+ * `peer` rides along opaquely: it is whatever the original session's verifyPeer resolved with,
+ * and a resumed session (which has no Certificate message to verify) reports it as its own —
+ * sound only because the ticket store keys tickets by the full trust configuration.
+ * @typedef {object} ResumptionOffer
+ * @property {Uint8Array} identity the ticket
+ * @property {Uint8Array} psk
+ * @property {import('./keyschedule.js').ScheduleHash} hash the hash the PSK was minted under
+ * @property {() => number} obfuscatedTicketAge uint32 per RFC 8446 s4.2.11.1
+ * @property {object} [peer]
+ */
+
+/**
+ * What a NewSessionTicket becomes by the time a caller sees it: the wire fields that govern
+ * offering (lifetime, age_add) plus the derived PSK and everything needed to check a future
+ * selection against it. `maxEarlyDataSize` is recorded for honesty but never acted on: 0-RTT
+ * is deliberately not implemented (see the driver's note).
+ * @typedef {object} CapturedTicket
+ * @property {Uint8Array} identity
+ * @property {Uint8Array} psk
+ * @property {import('./keyschedule.js').ScheduleHash} hash
+ * @property {number} cipherSuite
+ * @property {number} lifetimeSec
+ * @property {number} ageAdd
+ * @property {number | null} maxEarlyDataSize
+ * @property {string | null} alpnProtocol
+ * @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.
+ * @typedef {object} TlsDeps
+ * @property {(n: number) => Uint8Array} [randomBytes]
+ * @property {(algorithm: object, group: number) => Promise<CryptoKeyPair>} [generateKeyPair]
+ */
+
+/**
+ * What a completed handshake reports about itself.
+ * @typedef {object} TlsSessionInfo
+ * @property {number} version negotiated version, `0x0304` or `0x0303`
+ * @property {number} cipherSuite negotiated suite
+ * @property {number} group negotiated key-exchange group
+ * @property {string | null} alpnProtocol
+ * @property {string} hostname the identity the certificate was required to prove
+ * @property {boolean} [extendedMasterSecret] TLS 1.2 only: whether RFC 7627 was in effect
+ * @property {boolean} [resumed] TLS 1.3 only: the server accepted the offered resumption PSK,
+ *   so no certificate crossed the wire on THIS connection; the identity is the one validated
+ *   by the original handshake the ticket came from
+ */
+
+/**
+ * A live TLS session: a plaintext duplex plus what was negotiated to get it.
+ * @typedef {object} TlsSession
+ * @property {ReadableStream<Uint8Array>} readable
+ * @property {WritableStream<Uint8Array>} writable
+ * @property {import('./record.js').RecordLayer} record
+ * @property {object} peer whatever `verifyPeer` resolved with: the validated leaf
+ * @property {TlsSessionInfo} info
+ * @property {() => Promise<void>} close
+ */
+
+/**
+ * Run a TLS handshake over a byte duplex, negotiating the version, and return the plaintext
+ * duplex above it. The default offer is [TLS 1.3, TLS 1.2]; `options.versions` narrows it.
+ *
+ * @param {object} args
+ * @param {ByteDuplex} args.transport
+ * @param {string} args.hostname the identity the certificate must prove, and the SNI sent
+ * @param {import('./handshake.js').VerifyPeer} args.verifyPeer
+ *   Must throw to reject. Resolves with the validated leaf; its SPKI is the only key either
+ *   driver will accept a handshake signature from. Receives the peer's stapled OCSP response,
+ *   when there is one, as its third argument.
+ * @param {TlsOptions} [args.options]
+ * @param {TlsDeps} [args.deps]
+ * @returns {Promise<TlsSession>}
+ */
+export async function connectTls({ transport, hostname, verifyPeer, options = {}, deps = {} }) {
+  if (typeof verifyPeer !== 'function') {
+    // Refusing to start is the only safe default. A missing verifier must never read as "skip".
+    throw new TlsError(
+      codes.CONFIG_INVALID,
+      'connectTls requires a verifyPeer function; there is no unverified mode',
+    );
+  }
+  const versions = normalizeVersions(options.versions);
+  const record = new RecordLayer(transport, {
+    maxHandshakeMessage: options.maxHandshakeMessage,
+    maxKeyUpdates: options.maxKeyUpdates,
+  });
+  // Until the ServerHello picks, the record layer speaks the LOWEST version offered. The two
+  // semantics that differ before any ServerHello are alert tolerance and CCS handling, and the
+  // 1.2 discipline is right for both while 1.2 is a version we are willing to end up on: a 1.2
+  // server may send warning alerts (unrecognized_name, famously) that must not kill an offer
+  // that includes 1.2, and a CCS before ServerHello is fatal in every version — surfaced as an
+  // event here and refused by expectServerHello above. Once the ServerHello lands the version
+  // is pinned for real, before any key is installed.
+  record.setVersion(versions.includes(TLS12) ? TLS12 : TLS13);
+  try {
+    return await drive({ record, hostname, verifyPeer, options, deps, versions });
+  } catch (err) {
+    // Leaving a peer waiting on a half-open connection is a real interop problem, and the alert
+    // is the only signal a server operator gets about why we hung up. Best effort: the transport
+    // may already be gone, and the original error is what the caller needs.
+    try {
+      await record.abort();
+    } catch {
+      /* transport already unusable */
+    }
+    throw err;
+  }
+}
+
+async function drive({ record, hostname, verifyPeer, options, deps, versions }) {
+  const offers13 = versions.includes(TLS13);
+  const offers12 = versions.includes(TLS12);
+  const alpn = options.alpn ?? [ALPN_HTTP11];
+  const groups = options.groups ?? SUPPORTED_GROUPS;
+  const offerGroups = options.offerGroups ?? DEFAULT_OFFER_GROUPS;
+  // Suites for every offered version, 1.3 first. negotiateCipher later re-checks the family of
+  // the server's pick against the negotiated version, so a union offer cannot be abused to run
+  // a 1.3 suite under 1.2 or the reverse.
+  const ciphers = options.ciphers ?? [
+    ...(offers13 ? TLS13_CIPHERS : []),
+    ...(offers12 ? TLS12_CIPHERS : []),
+  ];
+
+  // --- resumption offer ----------------------------------------------------------------------
+  // Everything about the offered PSK that later steps need is derived once, up front: the Early
+  // Secret and binder key here (they depend only on the PSK), the binder itself per hello (it
+  // depends on each hello's bytes). psk_dhe_ke is the only mode ever offered, so acceptance
+  // still runs a fresh key exchange and a leaked ticket cannot unlock recorded traffic.
+  let pskOffer = null;
+  if (options.psk) {
+    const { identity, psk, hash, obfuscatedTicketAge, peer } = options.psk;
+    if (!offers13) {
+      throw new TlsError(codes.CONFIG_INVALID,
+        'options.psk offers a TLS 1.3 resumption PSK but TLS 1.3 is not among the offered versions');
+    }
+    // The PSK can only be selected together with a suite of its own hash (RFC 8446 s4.2.11).
+    // Offering one no offered suite could carry is a wiring bug upstream, not a server choice,
+    // and must fail here rather than surface as a mysteriously-always-full handshake.
+    const usable = ciphers.some((c) => CIPHER_PARAMS[c]?.hash === hash);
+    if (!usable) {
+      throw new TlsError(codes.CONFIG_INVALID,
+        `options.psk was minted under ${hash} but no offered cipher suite uses that hash`,
+        { hash, ciphers });
+    }
+    const early = await earlySecret(hash, psk);
+    pskOffer = {
+      identity, psk, hash, obfuscatedTicketAge, peer: peer ?? null,
+      earlySecret: early,
+      binderKey: await resumptionBinderKey(hash, early),
+      binderLen: hashLength(hash),
+    };
+  }
+
+  // --- ClientHello ---------------------------------------------------------------------------
+  // ONE hello for every offered version. Key shares ride in a 1.3-only extension, so they are
+  // generated only when 1.3 is on the table; a 1.2-only offer must not pay for a key it can
+  // never use (and must stay byte-identical to what handshakeTls12 always sent).
+  const keyShares = [];
+  if (offers13) {
+    for (const g of offerGroups) keyShares.push(await generateKeyShare(g, deps));
+  }
+  const hello = buildClientHello({
+    hostname,
+    keyShares,
+    groups,
+    alpn,
+    ciphers,
+    versions,
+    random: options.clientRandom,
+    legacySessionId: options.legacySessionId,
+    psk: pskOffer && {
+      identity: pskOffer.identity,
+      obfuscatedTicketAge: pskOffer.obfuscatedTicketAge(),
+      binderLen: pskOffer.binderLen,
+    },
+    randomBytes: deps.randomBytes,
+  });
+  if (pskOffer) {
+    // The binder (RFC 8446 s4.2.11.2): an HMAC under the binder key over the transcript of THIS
+    // hello truncated just before the binders list, hashed with the PSK's OWN hash — the
+    // negotiated suite does not exist yet and has no say. For the first hello that transcript
+    // is just the truncated message; no Transcript object exists this early, deliberately (its
+    // hash is the suite's, chosen later). The patched message is what the transcript and the
+    // wire both get, so the binder is inside every later hash of this hello.
+    const truncatedHash = new Uint8Array(await crypto.subtle.digest(
+      pskOffer.hash, hello.message.subarray(0, hello.truncatedLength)));
+    setPskBinder(hello, await finishedVerifyData(pskOffer.hash, pskOffer.binderKey, truncatedHash));
+  }
+  await record.writeHandshake([hello.message]);
+
+  // --- ServerHello: the server picks, we dispatch --------------------------------------------
+  const first = expectServerHello(await record.nextHandshakeMessage(), offers12);
+  const sh = parseServerHello(first.body);
+
+  if (sh.isHelloRetryRequest && !offers13) {
+    // The HelloRetryRequest random is a fixed TLS 1.3 constant; an honest 1.2 server hits it
+    // with probability 2^-256. Seeing it means a 1.3 message was spliced into this handshake.
+    throw new TlsError(
+      codes.TLS_HANDSHAKE,
+      'ServerHello.random is the TLS 1.3 HelloRetryRequest sentinel, which cannot occur in an ' +
+        'honest TLS 1.2 handshake',
+    );
+  }
+
+  // HelloRetryRequest is TLS 1.3 only, so an HRR decides the version by itself; the 1.3 driver
+  // re-runs negotiateVersion on the real ServerHello that follows it. Otherwise the ServerHello
+  // decides here — and this call, with the full offered list, is what makes the RFC 8446 s4.1.3
+  // downgrade sentinel and the not-offered check live.
+  const version = sh.isHelloRetryRequest
+    ? TLS13
+    : negotiateVersion(sh, { offeredVersions: versions });
+
+  // The suite is known now, from either the HelloRetryRequest or the real ServerHello, so the
+  // transcript can be created exactly once under the correct hash. It is fed the ClientHello
+  // only; folding in the ServerHello is the driver's job, because the 1.3 driver may first have
+  // to replace the ClientHello with its message_hash form (RFC 8446 s4.4.1).
+  const { suite, params } = negotiateCipher(sh, { offeredCiphers: hello.offeredCiphers, version });
+  const transcript = new Transcript(params.hash, { maxBytes: options.maxTranscriptBytes });
+  transcript.update(hello.message);
+
+  const ctx = {
+    record,
+    transcript,
+    hello,
+    serverHello: sh,
+    rawServerHello: first.raw,
+    suite,
+    params,
+    hostname,
+    verifyPeer,
+    options,
+    deps,
+    offer: { versions, ciphers: hello.offeredCiphers, groups, offerGroups, alpn, keyShares,
+      psk: pskOffer },
+  };
+
+  if (version === TLS13) {
+    // Pin the record layer before the driver reads on: a 1.3 server's compatibility CCS may
+    // arrive right behind the ServerHello and must be dropped, not surfaced as a 1.2 key-change
+    // event. No keys exist yet, so the pin is still legal.
+    record.setVersion(TLS13);
+    return continueTls13(ctx);
+  }
+  // version can only be TLS12 here (negotiateVersion refuses anything unoffered), and the
+  // record layer is already in 1.2 mode: TLS12 ∈ versions is what put it there.
+  return continueTls12(ctx);
+}