tunnelfetch 1.0.0

package/types/tls/keyschedule.d.ts

@@ -0,0 +1,272 @@
+/**
+ * The only hashes reachable through this schedule; see the module comment for why the type
+ * refuses the rest of WebCrypto's registry.
+ * @typedef {'SHA-256' | 'SHA-384'} ScheduleHash
+ */
+/**
+ * @param {ScheduleHash} hash
+ * @returns {number} digest length in bytes; throws for any other hash name
+ */
+export function hashLength(hash: ScheduleHash): number;
+/**
+ * HMAC-Hash(key, data) for a single message. For repeated MACs under one key, import once with
+ * importHmacKey and call crypto.subtle.sign directly instead.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} keyBytes
+ * @param {Uint8Array} data
+ * @returns {Promise<Uint8Array>}
+ */
+export function hmac(hash: ScheduleHash, keyBytes: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/**
+ * HKDF-Extract(salt, IKM) = HMAC-Hash(salt, IKM). RFC 5869 s2.2.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} salt
+ * @param {Uint8Array} ikm
+ * @returns {Promise<Uint8Array>}
+ */
+export function hkdfExtract(hash: ScheduleHash, salt: Uint8Array, ikm: Uint8Array): Promise<Uint8Array>;
+/**
+ * HKDF-Expand(PRK, info, L). RFC 5869 s2.3: T(i) = HMAC(PRK, T(i-1) || info || i), i in 1..N.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} prk
+ * @param {Uint8Array} info
+ * @param {number} length
+ * @returns {Promise<Uint8Array>}
+ */
+export function hkdfExpand(hash: ScheduleHash, prk: Uint8Array, info: Uint8Array, length: number): Promise<Uint8Array>;
+/**
+ * The HkdfLabel struct from RFC 8446 s7.1, exported separately so the tests can compare our
+ * encoding byte-for-byte against the `info` fields printed in the RFC 8448 traces:
+ *
+ *   struct {
+ *     uint16 length;
+ *     opaque label<7..255>;   // "tls13 " + Label
+ *     opaque context<0..255>;
+ *   } HkdfLabel;
+ *
+ * @param {string} label label WITHOUT the "tls13 " prefix
+ * @param {Uint8Array} context
+ * @param {number} length
+ * @returns {Uint8Array}
+ */
+export function hkdfLabel(label: string, context: Uint8Array, length: number): Uint8Array;
+/**
+ * HKDF-Expand-Label(Secret, Label, Context, Length). RFC 8446 s7.1.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} secret
+ * @param {string} label
+ * @param {Uint8Array} context
+ * @param {number} length
+ * @returns {Promise<Uint8Array>}
+ */
+export function hkdfExpandLabel(hash: ScheduleHash, secret: Uint8Array, label: string, context: Uint8Array, length: number): Promise<Uint8Array>;
+/**
+ * Derive-Secret(Secret, Label, Messages) — the transcript is passed already hashed.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} secret
+ * @param {string} label
+ * @param {Uint8Array} transcriptHash
+ * @returns {Promise<Uint8Array>}
+ */
+export function deriveSecret(hash: ScheduleHash, secret: Uint8Array, label: string, transcriptHash: Uint8Array): Promise<Uint8Array>;
+/**
+ * @param {ScheduleHash} hash
+ * @returns {Promise<Uint8Array>}
+ */
+export function emptyHash(hash: ScheduleHash): Promise<Uint8Array>;
+/**
+ * Early Secret = HKDF-Extract(salt: 0, IKM: PSK or zeros).
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array | null} [psk]
+ * @returns {Promise<Uint8Array>}
+ */
+export function earlySecret(hash: ScheduleHash, psk?: Uint8Array | null): Promise<Uint8Array>;
+/**
+ * Handshake Secret = HKDF-Extract(Derive-Secret(early, "derived", ""), ECDHE).
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} early
+ * @param {Uint8Array} ecdheShared
+ * @returns {Promise<Uint8Array>}
+ */
+export function deriveHandshakeSecret(hash: ScheduleHash, early: Uint8Array, ecdheShared: Uint8Array): Promise<Uint8Array>;
+/**
+ * Master Secret = HKDF-Extract(Derive-Secret(handshake, "derived", ""), 0).
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} handshakeSecret
+ * @returns {Promise<Uint8Array>}
+ */
+export function deriveMasterSecret(hash: ScheduleHash, handshakeSecret: Uint8Array): Promise<Uint8Array>;
+/**
+ * {client,server}_handshake_traffic_secret. Transcript: ClientHello..ServerHello.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} handshakeSecret
+ * @param {Uint8Array} transcriptHash
+ * @returns {Promise<{ client: Uint8Array, server: Uint8Array }>}
+ */
+export function handshakeTrafficSecrets(hash: ScheduleHash, handshakeSecret: Uint8Array, transcriptHash: Uint8Array): Promise<{
+    client: Uint8Array;
+    server: Uint8Array;
+}>;
+/**
+ * {client,server}_application_traffic_secret_0 and (unless suppressed) exporter_master_secret.
+ *
+ * `exporter` defaults on so the RFC 8448 vectors and any exporter user get the full set, but the
+ * handshake driver passes false: this package exposes no TLS-exporter interface, so deriving
+ * exporter_master_secret on every connection is one HKDF-Expand-Label of provably dead work on
+ * the hot path. Suppressing it there removes that work without changing any observable behaviour.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} masterSecret
+ * @param {Uint8Array} transcriptHash
+ * @param {{ exporter?: boolean }} [opts]
+ * @returns {Promise<{ client: Uint8Array, server: Uint8Array, exporterMaster?: Uint8Array }>}
+ */
+export function applicationTrafficSecrets(hash: ScheduleHash, masterSecret: Uint8Array, transcriptHash: Uint8Array, { exporter }?: {
+    exporter?: boolean;
+}): Promise<{
+    client: Uint8Array;
+    server: Uint8Array;
+    exporterMaster?: Uint8Array;
+}>;
+/**
+ * resumption_master_secret. Transcript: ClientHello..client Finished.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} masterSecret
+ * @param {Uint8Array} transcriptHash
+ * @returns {Promise<Uint8Array>}
+ */
+export function resumptionMasterSecret(hash: ScheduleHash, masterSecret: Uint8Array, transcriptHash: Uint8Array): Promise<Uint8Array>;
+/**
+ * The PSK a NewSessionTicket names: HKDF-Expand-Label(res master, "resumption", nonce).
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} resumptionMaster
+ * @param {Uint8Array} ticketNonce
+ * @returns {Promise<Uint8Array>}
+ */
+export function resumptionPsk(hash: ScheduleHash, resumptionMaster: Uint8Array, ticketNonce: Uint8Array): Promise<Uint8Array>;
+/**
+ * binder_key = Derive-Secret(Early Secret, "res binder", "") — RFC 8446 s7.1, the resumption
+ * variant. The "ext binder" sibling for externally provisioned PSKs is deliberately absent:
+ * this package mints PSKs only from NewSessionTicket, so an external-PSK binder key would be
+ * dead code with a security label on it. The binder value itself is finishedVerifyData over
+ * this key (RFC 8446 s4.2.11.2: "the PskBinderEntry is computed in the same way as the
+ * Finished message but with the BaseKey being the binder_key").
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} early the Early Secret extracted from the PSK being offered
+ * @returns {Promise<Uint8Array>}
+ */
+export function resumptionBinderKey(hash: ScheduleHash, early: Uint8Array): Promise<Uint8Array>;
+/**
+ * finished_key = HKDF-Expand-Label(BaseKey, "finished", "", Hash.length). RFC 8446 s4.4.4.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} trafficSecret
+ * @returns {Promise<Uint8Array>}
+ */
+export function finishedKey(hash: ScheduleHash, trafficSecret: Uint8Array): Promise<Uint8Array>;
+/**
+ * verify_data = HMAC(finished_key, Transcript-Hash).
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} trafficSecret
+ * @param {Uint8Array} transcriptHash
+ * @returns {Promise<Uint8Array>}
+ */
+export function finishedVerifyData(hash: ScheduleHash, trafficSecret: Uint8Array, transcriptHash: Uint8Array): Promise<Uint8Array>;
+/**
+ * [sender]_write_key and [sender]_write_iv from a traffic secret. RFC 8446 s7.3.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} trafficSecret
+ * @param {number} keyLen
+ * @param {number} ivLen
+ * @returns {Promise<{ key: Uint8Array, iv: Uint8Array }>}
+ */
+export function trafficKeys(hash: ScheduleHash, trafficSecret: Uint8Array, keyLen: number, ivLen: number): Promise<{
+    key: Uint8Array;
+    iv: Uint8Array;
+}>;
+/**
+ * application_traffic_secret_N+1 for KeyUpdate. RFC 8446 s7.2.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} trafficSecret
+ * @returns {Promise<Uint8Array>}
+ */
+export function nextTrafficSecret(hash: ScheduleHash, trafficSecret: Uint8Array): Promise<Uint8Array>;
+/**
+ * PRF(secret, label, seed) = P_<hash>(secret, label + seed), where
+ * P_hash(secret, seed) = HMAC(secret, A(1) + seed) + HMAC(secret, A(2) + seed) + ...
+ * with A(0) = seed, A(i) = HMAC(secret, A(i-1)).
+ *
+ * TLS 1.2 replaced the 1.1 MD5/SHA-1 split PRF with a single suite-selected hash, which for
+ * every suite in constants.js is SHA-256 or SHA-384.
+ *
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} secret
+ * @param {string} label ASCII label, e.g. 'master secret'
+ * @param {Uint8Array} seed
+ * @param {number} length
+ * @returns {Promise<Uint8Array>}
+ */
+export function prf12(hash: ScheduleHash, secret: Uint8Array, label: string, seed: Uint8Array, length: number): Promise<Uint8Array>;
+/**
+ * master_secret = PRF(pre_master, "master secret", client_random + server_random)[0..47].
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} preMaster
+ * @param {Uint8Array} clientRandom
+ * @param {Uint8Array} serverRandom
+ * @returns {Promise<Uint8Array>}
+ */
+export function masterSecret12(hash: ScheduleHash, preMaster: Uint8Array, clientRandom: Uint8Array, serverRandom: Uint8Array): Promise<Uint8Array>;
+/**
+ * RFC 7627 extended master secret: the seed is the session hash (transcript through
+ * ClientKeyExchange) instead of the two randoms, which binds the master secret to the full
+ * handshake and kills the triple-handshake attack. This is the variant the handshake layer
+ * must offer and prefer; a server that refuses the extension still gets masterSecret12, but
+ * that acceptance is deliberately flagged by the handshake layer as a weaker session.
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} preMaster
+ * @param {Uint8Array} sessionHash
+ * @returns {Promise<Uint8Array>}
+ */
+export function extendedMasterSecret12(hash: ScheduleHash, preMaster: Uint8Array, sessionHash: Uint8Array): Promise<Uint8Array>;
+/**
+ * key_block = PRF(master, "key expansion", server_random + client_random). RFC 5246 s6.3.
+ * Note the randoms swap order relative to the master secret derivation — that asymmetry is in
+ * the RFC, and the tests pin it. AEAD suites have no MAC keys (macLen 0), so the block is
+ * client_write_key + server_write_key + client_write_IV + server_write_IV, where the "IV" is
+ * the 4-byte implicit GCM salt of RFC 5288.
+ *
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} master
+ * @param {Uint8Array} clientRandom
+ * @param {Uint8Array} serverRandom
+ * @param {{ keyLen: number, fixedIvLen: number, macLen?: number }} lens
+ * @returns {Promise<{ clientWriteKey: Uint8Array, serverWriteKey: Uint8Array,
+ *   clientWriteIv: Uint8Array, serverWriteIv: Uint8Array,
+ *   clientWriteMacKey?: Uint8Array, serverWriteMacKey?: Uint8Array }>} MAC keys present only
+ *   when macLen > 0, which no AEAD suite ever passes
+ */
+export function keyBlock12(hash: ScheduleHash, master: Uint8Array, clientRandom: Uint8Array, serverRandom: Uint8Array, lens: {
+    keyLen: number;
+    fixedIvLen: number;
+    macLen?: number;
+}): Promise<{
+    clientWriteKey: Uint8Array;
+    serverWriteKey: Uint8Array;
+    clientWriteIv: Uint8Array;
+    serverWriteIv: Uint8Array;
+    clientWriteMacKey?: Uint8Array;
+    serverWriteMacKey?: Uint8Array;
+}>;
+/**
+ * verify_data = PRF(master, "client finished" | "server finished", Hash(messages))[0..11].
+ * 12 bytes for every suite this package negotiates (RFC 5246 s7.4.9).
+ * @param {ScheduleHash} hash
+ * @param {Uint8Array} master
+ * @param {'client finished' | 'server finished'} label
+ * @param {Uint8Array} transcriptHash
+ * @returns {Promise<Uint8Array>}
+ */
+export function verifyData12(hash: ScheduleHash, master: Uint8Array, label: "client finished" | "server finished", transcriptHash: Uint8Array): Promise<Uint8Array>;
+/**
+ * The only hashes reachable through this schedule; see the module comment for why the type
+ * refuses the rest of WebCrypto's registry.
+ */
+export type ScheduleHash = "SHA-256" | "SHA-384";

package/types/tls/record.d.ts

@@ -0,0 +1,361 @@
+/**
+ * A complete handshake message off the wire. `raw` includes the 4-byte header, which is the
+ * form the transcript hash consumes.
+ * @typedef {object} HandshakeMessage
+ * @property {number} type
+ * @property {Uint8Array} body
+ * @property {Uint8Array} raw
+ */
+/**
+ * Keys for one direction: a TLS 1.3 traffic `secret` (key and IV derived per RFC 8446 s7.3,
+ * KeyUpdate rotation possible) or raw TLS 1.2 key_block slices (no forward rotation).
+ * @typedef {{ cipher: number, secret: Uint8Array }
+ *   | { cipher: number, key: Uint8Array, iv: Uint8Array }} DirectionKeys
+ */
+/**
+ * @typedef {object} RecordLayerOptions
+ * @property {number} [maxHandshakeMessage] per-message cap; certificate chains dominate sizing
+ * @property {number} [maxKeyUpdates] received KeyUpdates before we call it a flood
+ * @property {number} [shutdownGraceMs] how long a courtesy close_notify or fatal alert may
+ *   block shutdown before being abandoned, default 2000; see _shutdown()
+ * @property {null | ((type: number, length: number) => number)} [padding] extra zero bytes per
+ *   record, TLS 1.3 only
+ * @property {null | ((msg: HandshakeMessage) => void | Promise<void>)} [onPostHandshake]
+ *   NewSessionTicket consumer; default is to discard
+ */
+export class RecordLayer {
+    /**
+     * @param {import('./connect.js').ByteDuplex} duplex ciphertext transport
+     * @param {RecordLayerOptions} [opts]
+     */
+    constructor({ readable, writable }: import("./connect.js").ByteDuplex, opts?: RecordLayerOptions);
+    _r: ByteReader;
+    _w: ByteWriter;
+    _maxHandshakeMessage: number;
+    _maxKeyUpdates: number;
+    _shutdownGraceMs: number;
+    _padding: ((type: number, length: number) => number) | null;
+    _onPostHandshake: ((msg: HandshakeMessage) => void | Promise<void>) | null;
+    _version: number;
+    /** @typedef {null | { aead: import('./aead.js').Aead, seq: bigint, cipher: number,
+     *   hash: import('./keyschedule.js').ScheduleHash,
+     *   secret: Uint8Array | null }} DirectionState */
+    /** @type {DirectionState} */
+    _send: {
+        aead: import("./aead.js").Aead;
+        seq: bigint;
+        cipher: number;
+        hash: import("./keyschedule.js").ScheduleHash;
+        secret: Uint8Array | null;
+    } | null;
+    /** @type {DirectionState} */
+    _recv: {
+        aead: import("./aead.js").Aead;
+        seq: bigint;
+        cipher: number;
+        hash: import("./keyschedule.js").ScheduleHash;
+        secret: Uint8Array | null;
+    } | null;
+    /** Handshake reassembly. Chunk list, not one growing buffer, so a peer drip-feeding a
+     * message in tiny records costs O(records), not O(records^2).
+     * @type {Uint8Array[]} */
+    _hsChunks: Uint8Array[];
+    _hsLen: number;
+    /** @type {{ type: number, len: number } | null} header of the message being assembled */
+    _hsHeader: {
+        type: number;
+        len: number;
+    } | null;
+    _handshakeComplete: boolean;
+    _closedByPeer: boolean;
+    _closedLocally: boolean;
+    /** @type {TlsError | null} first protocol error; sticky */
+    _fatal: TlsError | null;
+    _anyRecordWritten: boolean;
+    _reading: boolean;
+    /** All wire emission is funnelled through this chain. Two interleaved writers would
+     * reorder — or worse, reuse — AEAD sequence numbers, and with GCM a single reused nonce
+     * forfeits the key, so serialization here is a security control, not a convenience. */
+    _writeChain: Promise<void>;
+    _ignoredCcs: number;
+    _ignoredAlerts: number;
+    _emptyStreak: number;
+    _keyUpdatesReceived: number;
+    /**
+     * Pin the negotiated version. Chooses CCS semantics (1.3: compatibility noise to ignore;
+     * 1.2: a real key-change signal surfaced as `{ ccs: true }`), alert strictness, and AEAD
+     * framing. Must happen before any keys are installed.
+     * @param {number} version `TLS12` (0x0303) or `TLS13` (0x0304); anything else throws
+     */
+    setVersion(version: number): void;
+    get version(): number;
+    get handshakeComplete(): boolean;
+    /** The handshake driver calls this after the Finished exchange. Gates CCS and KeyUpdate. */
+    markHandshakeComplete(): void;
+    /**
+     * Install (or replace) the NewSessionTicket consumer after construction. Exists because the
+     * consumer needs secrets that do not exist when the record layer is built — the resumption
+     * master secret is derived from the transcript through the client Finished — so the driver
+     * wires it in at handshake completion. An exception it throws surfaces on the read path and
+     * fails the connection, which is the correct fate for a peer whose post-handshake messages do
+     * not parse.
+     * @param {null | ((msg: HandshakeMessage) => void | Promise<void>)} fn
+     */
+    setPostHandshake(fn: null | ((msg: HandshakeMessage) => void | Promise<void>)): void;
+    /**
+     * Install send-direction protection. Pass `secret` (a TLS 1.3 traffic secret; key and IV are
+     * derived per RFC 8446 s7.3, and KeyUpdate rotation becomes possible) or raw `key`+`iv`
+     * (TLS 1.2 key_block slices, which have no forward rotation). Sequence numbers reset.
+     * @param {DirectionKeys} keys
+     * @returns {Promise<void>}
+     */
+    setSendKeys({ cipher, secret, key, iv }: DirectionKeys): Promise<void>;
+    /**
+     * Install receive-direction protection. Refuses if a partially reassembled handshake
+     * message is pending: RFC 8446 s5.1 forbids a handshake message from spanning a key change,
+     * and enforcing it here — at the only point where the receive cipher can change — covers
+     * both driver-installed keys and KeyUpdate rotation with a single check.
+     * @param {DirectionKeys} keys
+     * @returns {Promise<void>}
+     */
+    setReceiveKeys({ cipher, secret, key, iv }: DirectionKeys): Promise<void>;
+    /**
+     * @param {{ cipher: number, secret?: Uint8Array, key?: Uint8Array, iv?: Uint8Array }} keys
+     * @returns {Promise<NonNullable<DirectionState>>}
+     */
+    _makeState({ cipher, secret, key, iv }: {
+        cipher: number;
+        secret?: Uint8Array;
+        key?: Uint8Array;
+        iv?: Uint8Array;
+    }): Promise<NonNullable<DirectionState>>;
+    /**
+     * Next handshake message during the handshake phase.
+     * Returns `{ type, body, raw }` (raw includes the 4-byte header, ready for the transcript),
+     * `{ ccs: true }` in TLS 1.2 mode when the peer's change_cipher_spec arrives, or `null` if
+     * the peer closed cleanly (which mid-handshake the driver should treat as failure).
+     * @returns {Promise<HandshakeMessage | { ccs: true } | null>}
+     */
+    nextHandshakeMessage(): Promise<HandshakeMessage | {
+        ccs: true;
+    } | null>;
+    /**
+     * Next application data chunk, or null at clean close_notify EOF. Post-handshake handshake
+     * messages (KeyUpdate, NewSessionTicket) are consumed transparently here.
+     * @returns {Promise<Uint8Array | null>}
+     */
+    readAppData(): Promise<Uint8Array | null>;
+    /**
+     * @template T
+     * @param {() => Promise<T>} fn
+     * @returns {Promise<T>}
+     */
+    _guardedRead<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * One protocol event: a complete handshake message, an app-data chunk, a 1.2 CCS, or close.
+     * All the "ignore and keep reading" cases (compat CCS, warning alerts, empty app records)
+     * loop in here, each behind a flood cap.
+     * @returns {Promise<{ kind: 'close' } | { kind: 'ccs' } | { kind: 'data', bytes: Uint8Array }
+     *   | { kind: 'handshake', msgType: number, body: Uint8Array, raw: Uint8Array }>}
+     */
+    _nextEvent(): Promise<{
+        kind: "close";
+    } | {
+        kind: "ccs";
+    } | {
+        kind: "data";
+        bytes: Uint8Array;
+    } | {
+        kind: "handshake";
+        msgType: number;
+        body: Uint8Array;
+        raw: Uint8Array;
+    }>;
+    /**
+     * Complete message off the reassembly buffer, if one is there.
+     * @returns {{ kind: 'handshake', msgType: number, body: Uint8Array, raw: Uint8Array } | null}
+     */
+    _takeHandshakeMessage(): {
+        kind: "handshake";
+        msgType: number;
+        body: Uint8Array;
+        raw: Uint8Array;
+    } | null;
+    /**
+     * Read one record off the wire and reduce it to (inner type, plaintext), or null once the
+     * peer has said close_notify. Handles decryption, the plaintext/ciphertext legality rules,
+     * and TLS 1.3 compatibility CCS.
+     * @returns {Promise<{ type: number, data: Uint8Array } | null>}
+     */
+    _nextPlaintextRecord(): Promise<{
+        type: number;
+        data: Uint8Array;
+    } | null>;
+    /**
+     * @param {Uint8Array} data
+     * @returns {'close' | 'ignored'} or throws for fatal alerts
+     */
+    _handleAlert(data: Uint8Array): "close" | "ignored";
+    /**
+     * KeyUpdate and NewSessionTicket arriving under application keys.
+     * @param {{ msgType: number, body: Uint8Array, raw: Uint8Array }} msg
+     */
+    _postHandshakeMessage({ msgType, body, raw }: {
+        msgType: number;
+        body: Uint8Array;
+        raw: Uint8Array;
+    }): Promise<void>;
+    /**
+     * Write one or more complete handshake messages, coalescing them into as few records as
+     * possible (the ClientHello flight and the 1.2 client second flight benefit) and
+     * fragmenting anything over 2^14.
+     * @param {Uint8Array | Uint8Array[]} messages
+     */
+    writeHandshake(messages: Uint8Array | Uint8Array[]): Promise<void>;
+    /**
+     * Write application data, fragmented to the record size limit.
+     * @param {Uint8Array} bytes
+     * @returns {Promise<void>}
+     */
+    writeAppData(bytes: Uint8Array): Promise<void>;
+    /** The one-byte compatibility (1.3) or key-change (1.2) CCS record. Always plaintext. */
+    writeChangeCipherSpec(): Promise<void>;
+    /**
+     * Post-handshake KeyUpdate initiated by us: send under current keys, then rotate our send
+     * chain. With `requestPeer` the peer must answer and rotate its own send keys too.
+     * @param {{ requestPeer?: boolean }} [opts]
+     * @returns {Promise<void>}
+     */
+    updateKeys({ requestPeer }?: {
+        requestPeer?: boolean;
+    }): Promise<void>;
+    /**
+     * @param {number} level `ALERT_LEVEL.warning` (1) or `ALERT_LEVEL.fatal` (2)
+     * @param {number} desc alert description byte, per `ALERT_DESC`
+     * @returns {Promise<void>}
+     */
+    sendAlert(level: number, desc: number): Promise<void>;
+    /**
+     * Clean shutdown: close_notify, then close the transport write side.
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    /**
+     * Shutdown, bounded.
+     *
+     * The alert is a courtesy: a peer that has stopped reading will never see it, and its write can
+     * therefore never complete once the transport's buffer fills. Awaiting that without a bound
+     * hangs close() forever on the ordinary path, and hangs abort() on the failure path — where it
+     * also swallows the error the caller was about to be given, turning a diagnosable failure into a
+     * request that simply never returns. So the courtesy gets a deadline and is then abandoned.
+     *
+     * Alert and FIN are one chained task so a single deadline covers both; queueing them separately
+     * would let a stalled alert consume one budget and the FIN another.
+     * @param {number} level
+     * @param {number} desc
+     */
+    _shutdown(level: number, desc: number): Promise<void>;
+    /**
+     * Abort: send a fatal alert naming why, then close. A peer left to time out on a dead
+     * connection is an interop bug of ours, not a neutral choice.
+     * @param {number} [desc] alert description byte, default internal_error
+     * @returns {Promise<void>}
+     */
+    abort(desc?: number): Promise<void>;
+    /**
+     * Application-data face of the connection as a {readable, writable} pair, for stacking the
+     * HTTP layer on top exactly like it would stack on a raw socket.
+     * @returns {import('./connect.js').ByteDuplex}
+     */
+    plaintextDuplex(): import("./connect.js").ByteDuplex;
+    _assertWritable(): void;
+    /**
+     * Serialize a wire-writing task behind every previously enqueued one.
+     * @template T
+     * @param {() => Promise<T>} fn
+     * @returns {Promise<T>}
+     */
+    _enqueueWrite<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * @param {number} type
+     * @param {Uint8Array} bytes
+     */
+    _writeFragmented(type: number, bytes: Uint8Array): Promise<void>;
+    /**
+     * Encrypt-and-frame one fragment. Only ever runs inside the write chain.
+     * @param {number} type
+     * @param {Uint8Array} chunk
+     */
+    _emit(type: number, chunk: Uint8Array): Promise<void>;
+    /**
+     * @param {number} type
+     * @param {Uint8Array} body
+     */
+    _writeRecord(type: number, body: Uint8Array): Promise<void>;
+    /** Derive application_traffic_secret_N+1 and swap the send state. Runs inside the chain. */
+    _rotateSend(): Promise<void>;
+    /**
+     * Record the first fatal error, tell the peer (best-effort), throw. Never returns.
+     * @param {string} code
+     * @param {string} message
+     * @param {Record<string, unknown>} [detail]
+     * @param {number} [alertDesc]
+     * @returns {never}
+     */
+    _fail(code: string, message: string, detail?: Record<string, unknown>, alertDesc?: number): never;
+    /**
+     * Fire-and-forget: awaiting a write here could park the failure path behind transport
+     * backpressure, and the error must reach our caller no matter what the peer does. The
+     * write chain still orders it before the transport close.
+     * @param {number} desc
+     */
+    _sendAlertBestEffort(desc: number): void;
+}
+/**
+ * A complete handshake message off the wire. `raw` includes the 4-byte header, which is the
+ * form the transcript hash consumes.
+ */
+export type HandshakeMessage = {
+    type: number;
+    body: Uint8Array;
+    raw: Uint8Array;
+};
+/**
+ * Keys for one direction: a TLS 1.3 traffic `secret` (key and IV derived per RFC 8446 s7.3,
+ * KeyUpdate rotation possible) or raw TLS 1.2 key_block slices (no forward rotation).
+ */
+export type DirectionKeys = {
+    cipher: number;
+    secret: Uint8Array;
+} | {
+    cipher: number;
+    key: Uint8Array;
+    iv: Uint8Array;
+};
+export type RecordLayerOptions = {
+    /**
+     * per-message cap; certificate chains dominate sizing
+     */
+    maxHandshakeMessage?: number | undefined;
+    /**
+     * received KeyUpdates before we call it a flood
+     */
+    maxKeyUpdates?: number | undefined;
+    /**
+     * how long a courtesy close_notify or fatal alert may
+     * block shutdown before being abandoned, default 2000; see _shutdown()
+     */
+    shutdownGraceMs?: number | undefined;
+    /**
+     * extra zero bytes per
+     * record, TLS 1.3 only
+     */
+    padding?: ((type: number, length: number) => number) | null | undefined;
+    /**
+     * NewSessionTicket consumer; default is to discard
+     */
+    onPostHandshake?: ((msg: HandshakeMessage) => void | Promise<void>) | null | undefined;
+};
+import { ByteReader } from '../util/bytes.js';
+import { ByteWriter } from '../util/bytes.js';
+import { TlsError } from '../errors.js';