@browsercore/testing 0.1.2 → 0.2.0

package/dist/e2e/parse-clienthello.js

@@ -0,0 +1,343 @@
+/**
+ * Minimal TLS 1.2+ ClientHello parser for the E2E TLS sink server.
+ *
+ * Parses the wire bytes a sink captured *before* TLS parsing, exposing the
+ * fields the e2e test matrix (T2–T9 in the plan) asserts on: cipher suites,
+ * extension types / order, ALPN protocols, SNI hostname, supported_versions.
+ *
+ * The parser is intentionally lenient about trailing data — it reads only the
+ * ClientHello body and stops. It does NOT validate cryptographic integrity;
+ * that is the handshake's job. All offsets are computed dynamically from the
+ * parsed structure (never hardcoded) so the same code works whether the input
+ * is a bare handshake message or a full TLS record (the caller strips the
+ * 5-byte record header via {@link parseClientHello}).
+ *
+ * This module merges the original minimal parser (shipped on `main`) with the
+ * E2E TLS sink server infrastructure (from `feat/e2e-sink`): the `EXT` constant
+ * table, `ClientHelloParseError`, richer offset/length metadata on
+ * {@link ParsedClientHello}, and GREASE utilities from the sink branch are
+ * retained alongside the `decodeSni`, `decodeAlpn`, `decodeSupportedVersions`
+ * accessors from `main`.
+ */
+// --- Extension-type constants (IANA) ------------------------------------
+export const EXT = {
+    SERVER_NAME: 0x0000,
+    SUPPORTED_VERSIONS: 0x002b,
+    APPLICATION_LAYER_PROTOCOL_NEGOTIATION: 0x0010,
+    KEY_SHARE: 0x0033,
+    SUPPORTED_GROUPS: 0x000a,
+    PSK_KEY_EXCHANGE_MODES: 0x002d,
+    SIGNATURE_ALGORITHMS: 0x000d,
+};
+// --- Errors -------------------------------------------------------------
+/** Thrown when the input is too short to be a valid ClientHello. */
+export class ClientHelloParseError extends Error {
+    kind = "ClientHelloParseError";
+    byteOffset;
+    cause;
+    constructor(message, byteOffset, options) {
+        super(message, options);
+        this.name = "ClientHelloParseError";
+        this.byteOffset = byteOffset;
+        this.cause = options?.cause;
+    }
+}
+// --- Parser helpers -----------------------------------------------------
+/** Read a big-endian uint16 at `offset`. */
+function readUint16(buf, offset) {
+    return (buf[offset] << 8) | buf[offset + 1];
+}
+/**
+ * Parse a TLS record header. Returns the offset of the handshake message that
+ * follows (i.e. 5 for a well-formed record) or `null` if the input does not
+ * start with a Handshake record (content type 0x16).
+ *
+ * Callers that already stripped the record header can pass the raw handshake
+ * message directly to {@link parseClientHello}.
+ */
+export function peekRecordHeader(buf) {
+    if (buf.length < 5)
+        return null;
+    const contentType = buf[0];
+    if (contentType !== 0x16)
+        return null; // Not a Handshake record.
+    // Bytes 1-2: record version (0x0303). Bytes 3-4: fragment length.
+    return 5;
+}
+/**
+ * Parse a ClientHello from raw wire bytes.
+ *
+ * Accepts either a full TLS Handshake record (5-byte header + handshake
+ * message) or a bare handshake message (type + 24-bit length + body). The
+ * function auto-detects the record header by content type.
+ *
+ * Distinct from the JA3 `parseClientHello` in `@browsercore/testing`'s
+ * fingerprint module (which returns JA3 segments). This parser returns the
+ * full structural breakdown (cipher suites, extensions, SNI, ALPN, etc.) for
+ * the e2e test matrix.
+ *
+ * @param buf Raw bytes as seen on the wire.
+ * @throws {ClientHelloParseError} if the input is malformed or truncated.
+ */
+export function parseClientHello(buf) {
+    let o = 0;
+    const recordOffset = peekRecordHeader(buf);
+    if (recordOffset !== null) {
+        o = recordOffset; // skip 5-byte record header.
+    }
+    const start = o;
+    if (o + 4 > buf.length) {
+        throw new ClientHelloParseError(`ClientHello truncated at handshake header (need 4 bytes at offset ${o}, have ${buf.length - o})`, o);
+    }
+    const handshakeType = buf[o];
+    if (handshakeType !== 0x01) {
+        throw new ClientHelloParseError(`Expected handshake type 0x01 (ClientHello), got 0x${handshakeType.toString(16).padStart(2, "0")}`, o);
+    }
+    const handshakeLength = (buf[o + 1] << 16) | (buf[o + 2] << 8) | buf[o + 3];
+    o += 4;
+    const bodyEnd = o + handshakeLength;
+    if (bodyEnd > buf.length) {
+        throw new ClientHelloParseError(`ClientHello body truncated (need ${handshakeLength} bytes, have ${buf.length - o})`, o);
+    }
+    // legacy_version (2) + random (32).
+    if (o + 34 > bodyEnd) {
+        throw new ClientHelloParseError("ClientHello too short for legacy_version + random", o);
+    }
+    const legacyVersion = readUint16(buf, o);
+    o += 2;
+    const random = buf.subarray(o, o + 32);
+    o += 32;
+    // session_id: length-prefixed.
+    const sessionIdLen = buf[o];
+    o += 1;
+    if (o + sessionIdLen > bodyEnd) {
+        throw new ClientHelloParseError("session_id extends past ClientHello body", o);
+    }
+    const sessionId = buf.subarray(o, o + sessionIdLen);
+    o += sessionIdLen;
+    // cipher_suites: 2-byte length prefix + (len/2) suites.
+    if (o + 2 > bodyEnd) {
+        throw new ClientHelloParseError("cipher_suites length truncated", o);
+    }
+    const csLen = readUint16(buf, o);
+    o += 2;
+    if (o + csLen > bodyEnd || csLen % 2 !== 0) {
+        throw new ClientHelloParseError("cipher_suites body truncated or odd length", o);
+    }
+    const suites = [];
+    for (let i = 0; i < csLen; i += 2) {
+        suites.push(readUint16(buf, o + i));
+    }
+    o += csLen;
+    // compression_methods: 1-byte length prefix + methods.
+    const compLen = buf[o];
+    o += 1;
+    if (o + compLen > bodyEnd) {
+        throw new ClientHelloParseError("compression_methods truncated", o);
+    }
+    const methods = [];
+    for (let i = 0; i < compLen; i++) {
+        methods.push(buf[o + i]);
+    }
+    o += compLen;
+    // extensions: 2-byte length prefix + extension list (may be absent).
+    const extensions = [];
+    if (o + 2 <= bodyEnd) {
+        const extLen = readUint16(buf, o);
+        o += 2;
+        const extEnd = o + extLen;
+        if (extEnd > bodyEnd) {
+            throw new ClientHelloParseError("extensions block truncated", o);
+        }
+        while (o + 4 <= extEnd) {
+            const extType = readUint16(buf, o);
+            const extLen2 = readUint16(buf, o + 2);
+            o += 4;
+            if (o + extLen2 > extEnd) {
+                throw new ClientHelloParseError(`extension 0x${extType.toString(16).padStart(4, "0")} data truncated`, o);
+            }
+            extensions.push({ type: extType, length: extLen2, data: buf.subarray(o, o + extLen2) });
+            o += extLen2;
+        }
+        o = extEnd;
+    }
+    void o; // body fully consumed; trailing bytes (next record) ignored.
+    return {
+        handshakeTypeOffset: start,
+        handshakeType,
+        handshakeLength,
+        legacyVersion,
+        random,
+        sessionId,
+        cipherSuites: suites,
+        compressionMethods: methods,
+        extensions,
+        totalLength: bodyEnd - start,
+    };
+}
+/**
+ * Wire-compatible alias of {@link parseClientHello}. Exported for callers that
+ * prefer the `parseClientHelloWire` name used by the E2E TLS sink server.
+ */
+export const parseClientHelloWire = parseClientHello;
+// --- Extension accessors ------------------------------------------------
+/**
+ * Find the first extension of the given type. Returns `undefined` if absent.
+ */
+export function findExtension(hello, type) {
+    return hello.extensions.find((e) => e.type === type);
+}
+// --- parse* accessors (feat/e2e-sink naming) ----------------------------
+/**
+ * Parse the SNI extension (type 0x0000) and return the first hostname.
+ *
+ * Layout: server_name_list_len(2) + entries. Each entry: name_type(1) +
+ * name_len(2) + name. name_type 0 = host_name.
+ */
+export function parseSniHostname(hello) {
+    const ext = findExtension(hello, EXT.SERVER_NAME);
+    if (ext === undefined || ext.data.length < 3)
+        return null;
+    let o = 0;
+    const listLen = readUint16(ext.data, o);
+    o += 2;
+    void listLen;
+    while (o + 3 <= ext.data.length) {
+        const nameType = ext.data[o];
+        const nameLen = readUint16(ext.data, o + 1);
+        o += 3;
+        if (o + nameLen > ext.data.length)
+            return null;
+        if (nameType === 0) {
+            return new TextDecoder().decode(ext.data.subarray(o, o + nameLen));
+        }
+        o += nameLen;
+    }
+    return null;
+}
+/**
+ * Parse the ALPN extension (type 0x0010) and return the offered protocols in
+ * wire order.
+ *
+ * Layout: protocol_list_len(2) + entries. Each entry: name_len(1) + name.
+ */
+export function parseAlpnProtocols(hello) {
+    const ext = findExtension(hello, EXT.APPLICATION_LAYER_PROTOCOL_NEGOTIATION);
+    if (ext === undefined || ext.data.length < 1)
+        return [];
+    let o = 0;
+    const listLen = readUint16(ext.data, o);
+    o += 2;
+    void listLen;
+    const protocols = [];
+    while (o + 1 <= ext.data.length) {
+        const nameLen = ext.data[o];
+        o += 1;
+        if (o + nameLen > ext.data.length)
+            break;
+        protocols.push(new TextDecoder().decode(ext.data.subarray(o, o + nameLen)));
+        o += nameLen;
+    }
+    return protocols;
+}
+/**
+ * Parse the supported_versions extension (type 0x002b) and return the offered
+ * versions in wire order.
+ *
+ * RFC 8446 §4.2.1.1: the client body is a 1-byte length-prefixed list of
+ * uint16 wire versions (`versions<2..254>`). The length byte counts the
+ * number of *bytes* of version data (always even), so the number of versions
+ * is `length / 2`.
+ */
+export function parseSupportedVersions(hello) {
+    const ext = findExtension(hello, EXT.SUPPORTED_VERSIONS);
+    if (ext === undefined || ext.data.length < 1)
+        return [];
+    const versionsLen = ext.data[0];
+    const versions = [];
+    let o = 1;
+    while (o + 2 <= 1 + versionsLen && o + 2 <= ext.data.length) {
+        versions.push(readUint16(ext.data, o));
+        o += 2;
+    }
+    return versions;
+}
+// --- decode* accessors (main branch naming) -----------------------------
+/**
+ * Decode the SNI server_name_list (extension 0x0000) into hostnames.
+ *
+ * RFC 6066 §3: server_name_list = length(2) || entries, each entry =
+ * name_type(1) || length(2) || name. We only handle name_type=0 (host_name).
+ *
+ * Returns all hostnames in the list. Use {@link parseSniHostname} for the
+ * first one only.
+ */
+export function decodeSni(hello) {
+    const ext = findExtension(hello, 0x0000);
+    if (ext === undefined || ext.data.length < 2) {
+        return [];
+    }
+    const names = [];
+    let pos = 0;
+    const listLen = readUint16(ext.data, pos);
+    pos += 2;
+    const end = pos + listLen;
+    while (pos + 3 <= end) {
+        const nameType = ext.data[pos];
+        const nameLen = readUint16(ext.data, pos + 1);
+        pos += 3;
+        if (pos + nameLen > end) {
+            break;
+        }
+        const nameBytes = ext.data.subarray(pos, pos + nameLen);
+        pos += nameLen;
+        if (nameType === 0) {
+            names.push(new TextDecoder().decode(nameBytes));
+        }
+    }
+    return names;
+}
+/**
+ * Decode the supported_versions extension (0x002b) for a client ClientHello.
+ *
+ * RFC 8446 §4.2.1: the client body is a length-prefixed list of uint16 wire
+ * versions. Returns the versions in wire order.
+ *
+ * Compatible alias of {@link parseSupportedVersions}.
+ */
+export function decodeSupportedVersions(hello) {
+    return parseSupportedVersions(hello);
+}
+/**
+ * Decode the ALPN extension (0x0010) into the offered protocol names.
+ *
+ * RFC 7301: the body is a length-prefixed list of length-prefixed UTF-8 names.
+ *
+ * Compatible alias of {@link parseAlpnProtocols}.
+ */
+export function decodeAlpn(hello) {
+    return parseAlpnProtocols(hello);
+}
+// --- GREASE sentinel detection ------------------------------------------
+/**
+ * The 16 GREASE sentinel values per RFC 8701: both bytes identical, low nibble
+ * 0xA. Used to detect / strip GREASE from cipher + extension assertions.
+ */
+export const GREASE_SENTINELS = [
+    0x0a0a, 0x1a1a, 0x2a2a, 0x3a3a, 0x4a4a, 0x5a5a, 0x6a6a, 0x7a7a,
+    0x8a8a, 0x9a9a, 0xaaaa, 0xbaba, 0xcaca, 0xdada, 0xeaea, 0xfafa,
+];
+const GREASE_SET = new Set(GREASE_SENTINELS);
+/** True if the given 16-bit wire value is a GREASE sentinel. */
+export function isGrease(value) {
+    return GREASE_SET.has(value);
+}
+/** Return the cipher suites with GREASE sentinels removed. */
+export function nonGreaseCipherSuites(hello) {
+    return hello.cipherSuites.filter((s) => !isGrease(s));
+}
+/** Return the extension types with GREASE sentinels removed. */
+export function nonGreaseExtensionTypes(hello) {
+    return hello.extensions.filter((e) => !isGrease(e.type)).map((e) => e.type);
+}
+//# sourceMappingURL=parse-clienthello.js.map

package/dist/e2e/parse-clienthello.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-clienthello.js","sourceRoot":"","sources":["../../src/e2e/parse-clienthello.ts"],"names":[],"mappings":"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"}

package/dist/e2e/sink-server.d.ts

@@ -0,0 +1,109 @@
+/**
+ * E2E TLS sink server for live handshake verification.
+ *
+ * Performs a **real** TLS 1.3 handshake against the `@browsercore/tls` client
+ * stack and returns the raw ClientHello bytes it saw on the wire — captured
+ * *before* Node's `tls` module parses them. This is the missing test oracle:
+ * every other TLS test in the stack runs against an in-process fixture; the
+ * sink exercises the full stack end-to-end over a real TCP socket.
+ *
+ * ## Two-socket tap
+ *
+ * Node's `tls` module parses the ClientHello before user code can see it, so
+ * the sink uses a two-socket tap (plan §2.3, Approach A):
+ *
+ * 1. A raw `node:net` server accepts the connection and pauses the socket.
+ * 2. It buffers the first bytes (the ClientHello TLS record) by reading until
+ *    the record length is satisfied.
+ * 3. It unshifts the buffer back onto the socket and wraps the socket in a
+ *    `tls.TLSSocket` (server-side) with a freshly generated self-signed
+ *    ECDSA P-256 cert.
+ * 4. The handshake completes; the captured bytes + parsed inspection are
+ *    returned via {@link TlsSinkServer.waitForHandshake}.
+ *
+ * The sink is single-shot by design: {@link TlsSinkServer.waitForHandshake}
+ * resolves on the first completed handshake. Tests create a fresh sink per
+ * case (ephemeral port, `maxConnections: 1`).
+ */
+/** Captured ClientHello — raw bytes + wall-clock capture time. */
+export interface ClientHelloCapture {
+    /** Full TLS record(s) as seen on the wire (record header + handshake). */
+    readonly raw: Uint8Array;
+    /** Epoch milliseconds when the capture completed. */
+    readonly receivedAt: number;
+}
+/** Result of a completed handshake against the sink. */
+export interface HandshakeResult {
+    /** The raw ClientHello the sink captured before TLS parsing. */
+    readonly clientHello: ClientHelloCapture;
+    /** Negotiated protocol version, e.g. "TLSv1.3". */
+    readonly protocolVersion: string;
+    /** Negotiated cipher suite, e.g. "TLS_AES_128_GCM_SHA256". */
+    readonly cipherSuite: string;
+    /** ALPN protocol negotiated, or null if none. */
+    readonly alpnProtocol: string | null;
+    /** SNI hostname the client sent, or null if omitted. */
+    readonly serverName: string | null;
+    /** Wall-clock handshake duration in milliseconds. */
+    readonly handshakeDurationMs: number;
+}
+/**
+ * Lightweight TLS 1.3 sink server.
+ *
+ * Not a general-purpose TLS server — it exists only to confirm a real
+ * handshake completes and to return the wire bytes it saw. All assertions
+ * live in the *test*; the sink just reports.
+ */
+export declare class TlsSinkServer {
+    private readonly server;
+    private readonly ctx;
+    private state;
+    private waiters;
+    private failers;
+    /** Host the sink listens on (always 127.0.0.1). */
+    readonly host: string;
+    /** Ephemeral port the sink listens on. */
+    readonly port: number;
+    /** ALPN protocols the sink negotiates (empty = no ALPN negotiation). */
+    private readonly alpnProtocols;
+    private constructor();
+    /**
+     * Start listening on an ephemeral port on 127.0.0.1.
+     *
+     * The returned sink is ready to accept one connection. The self-signed
+     * cert is generated at call time (throwaway — valid for 1 day).
+     *
+     * @param opts Optional configuration — ALPN protocols the sink should
+     *   negotiate (chooses the first client-offered protocol that matches).
+     */
+    static start(opts?: {
+        readonly alpnProtocols?: readonly string[];
+    }): Promise<TlsSinkServer>;
+    /** Wire up the server's connection handler. Must be called once. */
+    private attach;
+    /**
+     * Handle an incoming TCP connection: buffer the ClientHello, then hand the
+     * socket to a server-side TLSSocket for a real handshake.
+     */
+    private onConnection;
+    /**
+     * We have the raw ClientHello. Unshift it back onto the socket and wrap
+     * the socket in a server-side TLSSocket to complete the handshake.
+     */
+    private onClientHello;
+    /** Transition to the done state and resolve any waiters. */
+    private done;
+    /** Transition to the failed state and reject any waiters. */
+    private fail;
+    /**
+     * Resolve once a ClientHello has been captured and the handshake completed.
+     *
+     * @param timeoutMs Max wait in milliseconds (default 5000). The sink is
+     *   single-shot — only the first handshake resolves this promise.
+     * @throws {Error} on timeout or handshake failure.
+     */
+    waitForHandshake(timeoutMs?: number): Promise<HandshakeResult>;
+    /** Stop the server. Resolves once the underlying socket is closed. */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=sink-server.d.ts.map

package/dist/e2e/sink-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink-server.d.ts","sourceRoot":"","sources":["../../src/e2e/sink-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,kEAAkE;AAClE,MAAM,WAAW,kBAAkB;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,mDAAmD;IACnD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,qDAAqD;IACrD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACxC;AAUD;;;;;;GAMG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,OAAO,CAAgD;IAC/D,OAAO,CAAC,OAAO,CAAmC;IAElD,mDAAmD;IACnD,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAElD,OAAO,eAYN;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,GAAE;QAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CA2B9F;IAED,oEAAoE;IACpE,OAAO,CAAC,MAAM;IAId;;;OAGG;IACH,OAAO,CAAC,YAAY;IAuDpB;;;OAGG;IACH,OAAO,CAAC,aAAa;IA6CrB,4DAA4D;IAC5D,OAAO,CAAC,IAAI;IASZ,6DAA6D;IAC7D,OAAO,CAAC,IAAI;IASZ;;;;;;OAMG;IACH,gBAAgB,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,eAAe,CAAC,CAqB3D;IAED,sEAAsE;IACtE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CASpB;CACJ"}