tunnelfetch 1.0.0

package/types/pool.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Everything that decides whether two requests may share a socket. Mirrors what openConnection
+ * consumed to build the connection, because anything that influenced the connection must
+ * influence the key.
+ * @typedef {object} PoolKeyInput
+ * @property {string} scheme the URL protocol, colon included ('http:' | 'https:')
+ * @property {string} hostname
+ * @property {number} port
+ * @property {import('./proxy/index.js').ProxyConfig | null | undefined} proxy
+ * @property {import('./trust/index.js').TrustConfig | null | undefined} trust
+ * @property {import('./tls/connect.js').TlsOptions | null | undefined} tls
+ */
+/**
+ * The trust configuration is part of the key. Two requests to the same origin under different
+ * verification policies must not share a connection — the peer was validated under one policy and
+ * silently reusing it satisfies the other policy without ever having checked it.
+ *
+ * @param {PoolKeyInput} input
+ * @returns {string}
+ */
+export function poolKey({ scheme, hostname, port, proxy, trust, tls }: PoolKeyInput): string;
+/**
+ * What the pool stores: the connection object openConnection resolves to. The pool itself only
+ * ever calls `close?.()`, but naming the real type keeps take() useful to a caller.
+ * @typedef {import('./transport.js').Connection} PooledConnection
+ */
+/**
+ * @typedef {object} PoolOptions
+ * @property {number} [maxPerKey] idle connections kept per key, default 6
+ * @property {number} [maxTotal] idle connections kept across all keys, default 24
+ */
+/**
+ * Running counters, never reset. `discarded` includes connections refused at release time;
+ * `evicted` counts victims pushed out by a newer release under a full pool.
+ * @typedef {object} PoolStats
+ * @property {number} hits
+ * @property {number} misses
+ * @property {number} released
+ * @property {number} discarded
+ * @property {number} evicted
+ */
+export class ConnectionPool {
+    /**
+     * @param {PoolOptions} [opts]
+     */
+    constructor({ maxPerKey, maxTotal }?: PoolOptions);
+    /** @type {Map<string, Array<{conn: PooledConnection}>>} */
+    _idle: Map<string, Array<{
+        conn: PooledConnection;
+    }>>;
+    _total: number;
+    _maxPerKey: number;
+    _maxTotal: number;
+    _closed: boolean;
+    /** @type {PoolStats} */
+    stats: PoolStats;
+    get idleCount(): number;
+    /**
+     * Take an idle connection for `key`, or null. Most-recently-used first: it is likeliest live.
+     * @param {string} key
+     * @returns {PooledConnection | null}
+     */
+    take(key: string): PooledConnection | null;
+    /**
+     * Offer a connection back. Callers must have proven the body reached its declared end; this
+     * method cannot verify that and deliberately does not pretend to — `eligible` is the caller's
+     * assertion, and the one place it is computed is the HTTP framing layer.
+     * Idle entries carry no age, deliberately. Ageing them out would only narrow the window in
+     * which a peer reaps a socket we still believe in, never close it — the peer can hang up at any
+     * instant, including the one after the check. What actually makes reuse safe is the recovery in
+     * sendAndReceive(): a reused connection that ends without producing one response byte is proof
+     * the request was never seen, and it is re-sent on a fresh connection. An age field would look
+     * like a second line of defence while being neither necessary nor sufficient.
+     *
+     * @param {string} key
+     * @param {PooledConnection} conn
+     * @param {boolean} eligible
+     * @returns {boolean} whether the connection was retained
+     */
+    release(key: string, conn: PooledConnection, eligible: boolean): boolean;
+    /**
+     * Close and forget one connection that must not be reused.
+     * @param {PooledConnection} conn
+     * @returns {Promise<void>}
+     */
+    discard(conn: PooledConnection): Promise<void>;
+    /**
+     * Close everything. A Client that is done must call this or sockets leak for the isolate.
+     * @returns {Promise<void>}
+     */
+    closeAll(): Promise<void>;
+    _assertOpen(): void;
+}
+/**
+ * Everything that decides whether two requests may share a socket. Mirrors what openConnection
+ * consumed to build the connection, because anything that influenced the connection must
+ * influence the key.
+ */
+export type PoolKeyInput = {
+    /**
+     * the URL protocol, colon included ('http:' | 'https:')
+     */
+    scheme: string;
+    hostname: string;
+    port: number;
+    proxy: import("./proxy/index.js").ProxyConfig | null | undefined;
+    trust: import("./trust/index.js").TrustConfig | null | undefined;
+    tls: import("./tls/connect.js").TlsOptions | null | undefined;
+};
+/**
+ * What the pool stores: the connection object openConnection resolves to. The pool itself only
+ * ever calls `close?.()`, but naming the real type keeps take() useful to a caller.
+ */
+export type PooledConnection = import("./transport.js").Connection;
+export type PoolOptions = {
+    /**
+     * idle connections kept per key, default 6
+     */
+    maxPerKey?: number | undefined;
+    /**
+     * idle connections kept across all keys, default 24
+     */
+    maxTotal?: number | undefined;
+};
+/**
+ * Running counters, never reset. `discarded` includes connections refused at release time;
+ * `evicted` counts victims pushed out by a newer release under a full pool.
+ */
+export type PoolStats = {
+    hits: number;
+    misses: number;
+    released: number;
+    discarded: number;
+    evicted: number;
+};

package/types/proxy/direct.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @typedef {object} DirectOptions
+ * @property {{ hostname: string, port: number }} target
+ * @property {import('./index.js').ConnectFn} connect injected socket factory
+ * @property {AbortSignal} [signal]
+ */
+/**
+ * Dial the target itself. Resolves with the raw socket duplex; a refused or failed dial throws
+ * ProxyError (PROXY_UNREACHABLE) quoting the runtime's own message, which is the best
+ * diagnostic a caller will get.
+ *
+ * @param {DirectOptions} args
+ * @returns {Promise<import('./index.js').Duplex>}
+ */
+export function openDirect({ target, connect, signal }: DirectOptions): Promise<import("./index.js").Duplex>;
+export type DirectOptions = {
+    target: {
+        hostname: string;
+        port: number;
+    };
+    /**
+     * injected socket factory
+     */
+    connect: import("./index.js").ConnectFn;
+    signal?: AbortSignal | undefined;
+};

package/types/proxy/http-connect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Establish a CONNECT tunnel through an http/https proxy. Resolves with the tunnel duplex;
+ * every refusal (non-2xx, 407 with or without credentials, malformed reply) throws a
+ * ProxyError naming what the proxy answered.
+ *
+ * @param {HttpConnectOptions} args
+ * @returns {Promise<ProxyTunnel>}
+ */
+export function openHttpConnect({ proxy, target, connect, signal, limits }: HttpConnectOptions): Promise<ProxyTunnel>;
+/**
+ * The tunnel a proxy module hands back: the byte duplex plus the underlying socket, kept so a
+ * caller that must tear down the transport can reach past the wrapping streams.
+ */
+export type ProxyTunnel = import("./index.js").Duplex & {
+    socket: import("./index.js").Duplex;
+};
+export type HttpConnectOptions = {
+    /**
+     * protocol 'http' or 'https'
+     */
+    proxy: import("./index.js").ProxyConfig;
+    target: {
+        hostname: string;
+        port: number;
+    };
+    /**
+     * injected socket factory
+     */
+    connect: import("./index.js").ConnectFn;
+    signal?: AbortSignal | undefined;
+    /**
+     * CONNECT reply head cap, default 32768
+     */
+    limits?: {
+        maxProxyReplyBytes?: number;
+    } | undefined;
+};

package/types/proxy/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Normalise a proxy spec. Accepts a URL string (`http://user:pass@host:8080`,
+ * `socks5://host:1080`) or an object.
+ *
+ * `socks5h` is accepted as an alias of `socks5` because that is the spelling curl popularised for
+ * "resolve names at the proxy" — which is the only mode this package implements, since the
+ * runtime gives us no resolver and remote resolution is also what avoids leaking the target to
+ * the local DNS path.
+ *
+ * @param {string | ProxyConfig | null | undefined} spec
+ * @returns {ProxyConfig | null}
+ */
+export function parseProxy(spec: string | ProxyConfig | null | undefined): ProxyConfig | null;
+/**
+ * Open a byte tunnel to `target`, through `proxy` if given.
+ *
+ * @param {object} args
+ * @param {ProxyConfig | string | null} [args.proxy] null/absent means a direct connection
+ * @param {{hostname: string, port: number}} args.target
+ * @param {ConnectFn} args.connect socket factory, injected
+ * @param {AbortSignal} [args.signal]
+ * @param {object} [args.limits]
+ * @returns {Promise<Duplex & { proxied: boolean }>}
+ */
+export function openTunnel({ proxy, target, connect, signal, limits }: {
+    proxy?: string | ProxyConfig | null | undefined;
+    target: {
+        hostname: string;
+        port: number;
+    };
+    connect: ConnectFn;
+    signal?: AbortSignal | undefined;
+    limits?: object | undefined;
+}): Promise<Duplex & {
+    proxied: boolean;
+}>;
+/** Close a duplex without caring whether it was already gone. */
+export function closeQuietly(duplex: any): Promise<void>;
+export type Duplex = {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    opened?: Promise<unknown>;
+    close?: () => Promise<void>;
+};
+export type ConnectFn = (addr: {
+    hostname: string;
+    port: number;
+}, opts?: {
+    secureTransport?: "off" | "on" | "starttls";
+    allowHalfOpen?: boolean;
+}) => Duplex;
+export type ProxyConfig = {
+    protocol: "http" | "https" | "socks5" | "socks5h";
+    hostname: string;
+    port: number;
+    username?: string;
+    password?: string;
+};
+import { openDirect } from './direct.js';
+import { openHttpConnect } from './http-connect.js';
+import { openSocks5 } from './socks5.js';
+export { openDirect, openHttpConnect, openSocks5 };

package/types/proxy/socks5.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @typedef {object} Socks5Options
+ * @property {import('./index.js').ProxyConfig} proxy credentials trigger RFC 1929 user/pass auth
+ * @property {{ hostname: string, port: number }} target
+ * @property {import('./index.js').ConnectFn} connect injected socket factory
+ * @property {AbortSignal} [signal]
+ */
+/**
+ * Establish a SOCKS5 tunnel. Resolves with the tunnel duplex; every refusal (no acceptable
+ * auth method, rejected credentials, non-zero reply code, unframeable reply) throws a
+ * ProxyError naming the exact wire value the proxy sent.
+ *
+ * @param {Socks5Options} args
+ * @returns {Promise<import('./http-connect.js').ProxyTunnel>}
+ */
+export function openSocks5({ proxy, target, connect, signal }: Socks5Options): Promise<import("./http-connect.js").ProxyTunnel>;
+/**
+ * Encode DST.ADDR + DST.PORT. Prefers the domain form so the proxy resolves.
+ * @param {{ hostname: string, port: number }} target
+ * @returns {Uint8Array}
+ */
+export function encodeAddress(target: {
+    hostname: string;
+    port: number;
+}): Uint8Array;
+/**
+ * Minimal IPv6 text parser: `::` compression and a trailing embedded IPv4 are both real.
+ * Throws ConfigError on anything that does not expand to exactly 8 groups.
+ * @param {string} text
+ * @returns {Uint8Array} the 16 address bytes
+ */
+export function parseIpv6(text: string): Uint8Array;
+export type Socks5Options = {
+    /**
+     * credentials trigger RFC 1929 user/pass auth
+     */
+    proxy: import("./index.js").ProxyConfig;
+    target: {
+        hostname: string;
+        port: number;
+    };
+    /**
+     * injected socket factory
+     */
+    connect: import("./index.js").ConnectFn;
+    signal?: AbortSignal | undefined;
+};

package/types/tls/aead.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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: Uint8Array, seq: number | bigint): Uint8Array;
+/**
+ * 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 function createAead({ version, cipher, key, iv }: 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
+ * content type under 1.3, the header type under 1.2) or throws TLS_RECORD — never garbage.
+ */
+export type Aead = {
+    version: number;
+    encrypt: (seq: number | bigint, type: number, plaintext: Uint8Array, opts?: {
+        padding?: number;
+    }) => Promise<Uint8Array>;
+    decrypt: (seq: number | bigint, body: Uint8Array, header: Uint8Array) => Promise<{
+        type: number;
+        plaintext: Uint8Array;
+    }>;
+};
+export type AeadOptions = {
+    /**
+     * `TLS13` (default) or `TLS12`; picks nonce and AAD construction
+     */
+    version?: number | undefined;
+    /**
+     * cipher suite id, must have CIPHER_PARAMS
+     */
+    cipher: number;
+    key: Uint8Array;
+    /**
+     * the 12-byte static IV for TLS 1.3, the 4-byte implicit salt for
+     * TLS 1.2
+     */
+    iv: Uint8Array;
+};

package/types/tls/connect.d.ts

@@ -0,0 +1,280 @@
+/**
+ * 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 function connectTls({ transport, hostname, verifyPeer, options, deps }: {
+    transport: ByteDuplex;
+    hostname: string;
+    verifyPeer: import("./handshake.js").VerifyPeer;
+    options?: TlsOptions | undefined;
+    deps?: TlsDeps | undefined;
+}): Promise<TlsSession>;
+/**
+ * A byte duplex: what every layer in this package consumes and produces.
+ */
+export type ByteDuplex = {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+};
+/**
+ * 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.
+ */
+export type TlsOptions = {
+    /**
+     * versions to offer, from `TLS13` / `TLS12`. Default both.
+     */
+    versions?: number[] | undefined;
+    /**
+     * ALPN protocols to offer. Default `['http/1.1']`.
+     */
+    alpn?: string[] | undefined;
+    /**
+     * supported_groups, in preference order.
+     */
+    groups?: number[] | undefined;
+    /**
+     * 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.
+     */
+    offerGroups?: number[] | undefined;
+    /**
+     * cipher suites to offer, in preference order.
+     */
+    ciphers?: number[] | undefined;
+    /**
+     * fixed ClientHello.random, for reproducible handshakes.
+     */
+    clientRandom?: Uint8Array<ArrayBufferLike> | undefined;
+    /**
+     * fixed legacy_session_id, likewise.
+     */
+    legacySessionId?: Uint8Array<ArrayBufferLike> | undefined;
+    /**
+     * send the middlebox-compatibility ChangeCipherSpec.
+     * Default true.
+     */
+    compatibilityCcs?: boolean | undefined;
+    /**
+     * per-message cap; certificate chains dominate sizing.
+     */
+    maxHandshakeMessage?: number | undefined;
+    /**
+     * received KeyUpdates tolerated before it is called a flood.
+     */
+    maxKeyUpdates?: number | undefined;
+    /**
+     * cap on buffered handshake transcript.
+     */
+    maxTranscriptBytes?: number | undefined;
+    /**
+     * 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.
+     */
+    psk?: ResumptionOffer | undefined;
+    /**
+     * 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.
+     */
+    onSessionTicket?: ((ticket: CapturedTicket) => void) | undefined;
+};
+/**
+ * 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.
+ */
+export type ResumptionOffer = {
+    /**
+     * the ticket
+     */
+    identity: Uint8Array;
+    psk: Uint8Array;
+    /**
+     * the hash the PSK was minted under
+     */
+    hash: import("./keyschedule.js").ScheduleHash;
+    /**
+     * uint32 per RFC 8446 s4.2.11.1
+     */
+    obfuscatedTicketAge: () => number;
+    peer?: object | undefined;
+};
+/**
+ * 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).
+ */
+export type CapturedTicket = {
+    identity: Uint8Array;
+    psk: Uint8Array;
+    hash: import("./keyschedule.js").ScheduleHash;
+    cipherSuite: number;
+    lifetimeSec: number;
+    ageAdd: number;
+    maxEarlyDataSize: number | null;
+    alpnProtocol: string | null;
+    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.
+ */
+export type TlsDeps = {
+    randomBytes?: ((n: number) => Uint8Array) | undefined;
+    generateKeyPair?: ((algorithm: object, group: number) => Promise<CryptoKeyPair>) | undefined;
+};
+/**
+ * What a completed handshake reports about itself.
+ */
+export type TlsSessionInfo = {
+    /**
+     * negotiated version, `0x0304` or `0x0303`
+     */
+    version: number;
+    /**
+     * negotiated suite
+     */
+    cipherSuite: number;
+    /**
+     * negotiated key-exchange group
+     */
+    group: number;
+    alpnProtocol: string | null;
+    /**
+     * the identity the certificate was required to prove
+     */
+    hostname: string;
+    /**
+     * TLS 1.2 only: whether RFC 7627 was in effect
+     */
+    extendedMasterSecret?: boolean | undefined;
+    /**
+     * 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
+     */
+    resumed?: boolean | undefined;
+};
+/**
+ * A live TLS session: a plaintext duplex plus what was negotiated to get it.
+ */
+export type TlsSession = {
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    record: import("./record.js").RecordLayer;
+    /**
+     * whatever `verifyPeer` resolved with: the validated leaf
+     */
+    peer: object;
+    info: TlsSessionInfo;
+    close: () => Promise<void>;
+};