@browsercore/testing 0.1.0

package/dist/reference/reference.js

@@ -0,0 +1,323 @@
+/**
+ * Pluggable layered reference provider.
+ *
+ * The reference implementation is the source of truth for what a given browser
+ * profile SHOULD produce on the wire. Three backends are wrapped behind one
+ * facade:
+ *
+ * - `node-reference` (oracle) — Node's built-in crypto/dns/zlib/http
+ *   implementations, used as the spec oracle for primitive layers where Node IS
+ *   the reference (see `node-reference.ts`).
+ * - `curl-impersonate` (PRIMARY) — fast CI path; shells out to the
+ *   curl-impersonate binary to capture real traffic for a profile.
+ * - `real-browser` (SECONDARY) — loads pre-recorded captures from the
+ *   `captures/` directory, recorded from an actual browser.
+ *
+ * The {@link ReferenceProviderFacade} ties them together: capture resolves via
+ * primary then secondary; fingerprint is derived from the captured bytes; the
+ * node-reference oracle is exposed for primitive-layer comparisons.
+ *
+ * See docs/TEST-SUITE.md (Cat 3, 4, 14) for how references feed comparison.
+ */
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { computeJa3 } from "../fingerprint/ja3.js";
+import { computeJa4Fingerprint } from "../fingerprint/ja4.js";
+import { loadCaptureMeta } from "../golden/golden.js";
+import { TestingError } from "../errors.js";
+const execFileAsync = promisify(execFile);
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(here, "..", "..");
+const defaultCapturesDir = join(packageRoot, "captures");
+/** Raised when a reference provider cannot capture or fingerprint a profile. */
+export class ReferenceError extends TestingError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ReferenceError";
+    }
+}
+/**
+ * PRIMARY provider — shells out to curl-impersonate.
+ *
+ * `capture()` invokes the curl-impersonate binary against `url`, impersonating
+ * `profile`, and returns the raw bytes it observed on the wire. The binary
+ * must be on PATH (or in `command`); if it is missing, the call throws
+ * {@link ReferenceError} so the facade can fall back to the secondary.
+ */
+export class CurlImpersonateProvider {
+    kind = { kind: "curl-impersonate" };
+    command;
+    extraArgs;
+    constructor(options) {
+        this.command = options?.command ?? "curl-impersonate";
+        this.extraArgs = options?.extraArgs ?? [];
+    }
+    availableProfiles() {
+        // curl-impersonate ships these browser impersonation targets.
+        return [
+            "chrome-140",
+            "chrome-139",
+            "firefox-135",
+            "firefox-128",
+            "safari-18",
+            "edge-140",
+        ];
+    }
+    async capture(profile, url) {
+        const profileFlag = `--${String(profile)}`;
+        const args = [profileFlag, "--dump-traffic", ...this.extraArgs, url];
+        let stdout;
+        let stderr;
+        try {
+            const out = await execFileAsync(this.command, args, {
+                timeout: 30_000,
+                maxBuffer: 64 * 1024 * 1024,
+            });
+            stdout = out.stdout;
+            stderr = out.stderr;
+        }
+        catch (e) {
+            const cause = e instanceof Error ? e : new Error(String(e));
+            throw new ReferenceError(`curl-impersonate capture for ${String(profile)} failed: ${cause.message}`, { cause });
+        }
+        void stderr;
+        const bytes = parseDumpOutput(stdout);
+        return {
+            id: `${profile}/tls/client_hello`,
+            source: profileToSource(profile),
+            protocol: "tls",
+            bytes,
+            description: `curl-impersonate capture for ${String(profile)}`,
+        };
+    }
+    async fingerprint(profile) {
+        const capture = await this.capture(profile, "https://example.com");
+        return fingerprintFromTlsCapture(capture);
+    }
+}
+/**
+ * SECONDARY provider — loads pre-recorded captures from the `captures/` dir.
+ *
+ * `capture()` resolves a stored capture for the profile; `fingerprint()`
+ * derives a {@link Fingerprint} from the captured bytes (only TLS
+ * ClientHellos are fingerprinted — other protocols return a stub).
+ */
+export class RealBrowserCaptureProvider {
+    kind = { kind: "real-browser" };
+    capturesDir;
+    constructor(options) {
+        this.capturesDir = options?.capturesDir ?? defaultCapturesDir;
+    }
+    availableProfiles() {
+        // Discovery is driven by the captures manifest (captures/manifest.ts).
+        return [
+            "chrome-140",
+            "firefox-128",
+        ];
+    }
+    async capture(profile, _url) {
+        void _url;
+        const manifest = await import("../captures/manifest.js");
+        const entry = manifest.captures.find((c) => c.meta.profile === profile);
+        if (entry === undefined) {
+            throw new ReferenceError(`No pre-recorded capture for profile ${String(profile)}`);
+        }
+        return {
+            id: `${profile}/tls/client_hello`,
+            source: profileToSource(profile),
+            protocol: entry.meta.protocol,
+            bytes: entry.bytes,
+            description: entry.meta.description,
+        };
+    }
+    async fingerprint(profile) {
+        const capture = await this.capture(profile, "https://example.com");
+        if (capture.protocol !== "tls") {
+            throw new ReferenceError(`fingerprint() only supports TLS captures; got ${capture.protocol}`);
+        }
+        return fingerprintFromTlsCapture(capture);
+    }
+}
+/**
+ * Facade wrapping the node-reference oracle + primary (curl-impersonate) and
+ * secondary (real-browser) providers behind a single {@link ReferenceProvider}.
+ *
+ * `capture()` tries the primary first; if it fails (binary missing, network
+ * error, ...) it falls back to the secondary's pre-recorded captures. The
+ * node-reference oracle is exposed via {@link ReferenceProviderFacade.nodeOracle}
+ * for primitive-layer comparisons (crypto, dns, zlib, wire format) — those
+ * layers are NOT fingerprinted here; they live in `node-reference.ts`.
+ */
+export class ReferenceProviderFacade {
+    kind = { kind: "curl-impersonate" };
+    primary;
+    secondary;
+    constructor(options) {
+        this.primary = new CurlImpersonateProvider(options?.curl);
+        this.secondary = new RealBrowserCaptureProvider(options?.browser);
+    }
+    /**
+     * Node-reference oracle — the spec oracle for primitive layers where Node
+     * IS the reference (crypto, dns, zlib, wire format). NOT used for
+     * browser-fingerprint comparison; that is what the providers are for.
+     */
+    get nodeOracle() {
+        return nodeOracle;
+    }
+    availableProfiles() {
+        // Union of profiles from both providers, de-duplicated.
+        const seen = new Set();
+        const out = [];
+        for (const p of [...this.primary.availableProfiles(), ...this.secondary.availableProfiles()]) {
+            const key = String(p);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(p);
+        }
+        return out;
+    }
+    async capture(profile, url) {
+        try {
+            return await this.primary.capture(profile, url);
+        }
+        catch (primaryErr) {
+            const cause = primaryErr instanceof Error ? primaryErr : new Error(String(primaryErr));
+            // Fall back to the secondary provider's pre-recorded captures.
+            try {
+                return await this.secondary.capture(profile, url);
+            }
+            catch (secondaryErr) {
+                const secondaryCause = secondaryErr instanceof Error ? secondaryErr : new Error(String(secondaryErr));
+                throw new ReferenceError(`No reference available for ${String(profile)}: primary failed (${cause.message}), secondary failed (${secondaryCause.message})`, { cause: secondaryCause });
+            }
+        }
+    }
+    async fingerprint(profile) {
+        try {
+            return await this.primary.fingerprint(profile);
+        }
+        catch (primaryErr) {
+            const cause = primaryErr instanceof Error ? primaryErr : new Error(String(primaryErr));
+            try {
+                return await this.secondary.fingerprint(profile);
+            }
+            catch (secondaryErr) {
+                const secondaryCause = secondaryErr instanceof Error ? secondaryErr : new Error(String(secondaryErr));
+                throw new ReferenceError(`No fingerprint available for ${String(profile)}: primary failed (${cause.message}), secondary failed (${secondaryCause.message})`, { cause: secondaryCause });
+            }
+        }
+    }
+}
+/**
+ * Node-reference oracle re-export — the spec oracle for primitive layers.
+ *
+ * Imported lazily so the facade type references resolve without a cycle.
+ */
+import * as nodeOracle from "./node-reference.js";
+/** Construct the {@link ReferenceProvider} matching {@link ReferenceProviderKind}. */
+export function createReferenceProvider(kind, options) {
+    switch (kind.kind) {
+        case "curl-impersonate":
+            return new CurlImpersonateProvider(options);
+        case "real-browser":
+            return new RealBrowserCaptureProvider(options);
+    }
+}
+/**
+ * Construct the full {@link ReferenceProviderFacade} wrapping both providers
+ * plus the node-reference oracle. This is the recommended entry point for
+ * tests that want primary→secondary fallback.
+ */
+export function createReferenceFacade(options) {
+    return new ReferenceProviderFacade(options);
+}
+/** Map a {@link ProfileId} to its {@link CaptureSource} tag. */
+function profileToSource(profile) {
+    const p = String(profile);
+    if (p.startsWith("firefox"))
+        return "firefox-135";
+    if (p.startsWith("safari"))
+        return "safari-18";
+    if (p.startsWith("edge"))
+        return "edge-140";
+    return "chrome-140";
+}
+/**
+ * Parse curl-impersonate `--dump-traffic` output into raw bytes.
+ *
+ * The dump format is a hex dump with one line per record; we extract the hex
+ * payload between the markers. For now we assume the body is a contiguous hex
+ * block — adjust the parser if curl-impersonate's format differs.
+ */
+function parseDumpOutput(stdout) {
+    // Find the hex body — everything after the ">>> traffic <<<" marker.
+    const marker = ">>> traffic <<<";
+    const idx = stdout.indexOf(marker);
+    const body = idx === -1 ? stdout : stdout.slice(idx + marker.length);
+    const hex = body.replace(/[^0-9a-fA-F]/g, "");
+    if (hex.length === 0) {
+        throw new ReferenceError("curl-impersonate dump produced no hex bytes");
+    }
+    if (hex.length % 2 !== 0) {
+        throw new ReferenceError(`curl-impersonate dump produced odd-length hex (${hex.length})`);
+    }
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Derive a {@link Fingerprint} from a TLS ClientHello capture.
+ *
+ * Computes JA3 + JA4 from the raw bytes and reads the per-extension metadata
+ * (supported groups, signature algorithms, ALPN) from the sidecar
+ * `.meta.json` when available.
+ */
+function fingerprintFromTlsCapture(capture) {
+    const ja3 = computeJa3(capture.bytes);
+    const ja4 = computeJa4Fingerprint(capture.bytes);
+    // Read the sidecar meta for richer fields (signature algorithms, ALPN,
+    // supported curves). Fall back to empty arrays if missing.
+    let alpn = [];
+    let signatureAlgorithms = [];
+    let ellipticCurves = [];
+    try {
+        const meta = loadCaptureMeta(capture.id);
+        if (meta.protocol === "tls") {
+            // CaptureMeta doesn't carry ALPN/sigAlgs/curves yet; this is a
+            // placeholder for when the sidecar schema is extended.
+            void meta;
+            void alpn;
+            void signatureAlgorithms;
+            void ellipticCurves;
+        }
+    }
+    catch {
+        // Sidecar missing or unparseable — leave richer fields empty.
+    }
+    return {
+        ja3,
+        ja4: ja4.tag,
+        alpn,
+        cipherSuite: cipherSuiteName(ja4.tag),
+        protocolVersion: ja4.tag.slice(5, 7) || "unknown",
+        signatureAlgorithms,
+        ellipticCurves,
+    };
+}
+/**
+ * Extract a human-readable cipher-suite name from a JA4 tag.
+ *
+ * JA4 doesn't directly encode the negotiated cipher; this is a placeholder
+ * that returns the JA4_a segment for inspection. Real cipher-suite resolution
+ * requires parsing the ServerHello, which is out of scope for the capture.
+ */
+function cipherSuiteName(ja4Tag) {
+    const a = ja4Tag.split("_")[0] ?? "";
+    return a.length > 0 ? a : "unknown";
+}
+//# sourceMappingURL=reference.js.map

package/dist/reference/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../src/reference/reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3C,MAAM,kBAAkB,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AA+CzD,gFAAgF;AAChF,MAAM,OAAO,cAAe,SAAQ,YAAY;IAC5C,YAAY,OAAe,EAAE,OAA2B;QACpD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IACjC,CAAC;CACJ;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAuB;IAChB,IAAI,GAA0B,EAAE,IAAI,EAAE,kBAAkB,EAAW,CAAC;IACpE,OAAO,CAAS;IAChB,SAAS,CAAoB;IAE7C,YAAY,OAAgC;QACxC,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,kBAAkB,CAAC;QACtD,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,EAAE,CAAC;IAC9C,CAAC;IAED,iBAAiB;QACb,8DAA8D;QAC9D,OAAO;YACH,YAAyB;YACzB,YAAyB;YACzB,aAA0B;YAC1B,aAA0B;YAC1B,WAAwB;YACxB,UAAuB;SAC1B,CAAC;IACN,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAkB,EAAE,GAAW;QACzC,MAAM,WAAW,GAAG,KAAK,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;QACrE,IAAI,MAAc,CAAC;QACnB,IAAI,MAAc,CAAC;QACnB,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE;gBAChD,OAAO,EAAE,MAAM;gBACf,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;aAC9B,CAAC,CAAC;YACH,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;YACpB,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACxB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5D,MAAM,IAAI,cAAc,CACpB,gCAAgC,MAAM,CAAC,OAAO,CAAC,YAAY,KAAK,CAAC,OAAO,EAAE,EAC1E,EAAE,KAAK,EAAE,CACZ,CAAC;QACN,CAAC;QACD,KAAK,MAAM,CAAC;QACZ,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACtC,OAAO;YACH,EAAE,EAAE,GAAG,OAAO,mBAA0C;YACxD,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC;YAChC,QAAQ,EAAE,KAAK;YACf,KAAK;YACL,WAAW,EAAE,gCAAgC,MAAM,CAAC,OAAO,CAAC,EAAE;SACjE,CAAC;IACN,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAAkB;QAChC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;QACnE,OAAO,yBAAyB,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;CACJ;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA0B;IACnB,IAAI,GAA0B,EAAE,IAAI,EAAE,cAAc,EAAW,CAAC;IAChE,WAAW,CAAS;IAEpC,YAAY,OAA4B;QACpC,IAAI,CAAC,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,kBAAkB,CAAC;IAClE,CAAC;IAED,iBAAiB;QACb,uEAAuE;QACvE,OAAO;YACH,YAAyB;YACzB,aAA0B;SAC7B,CAAC;IACN,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAkB,EAAE,IAAY;QAC1C,KAAK,IAAI,CAAC;QACV,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;QACxE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,cAAc,CACpB,uCAAuC,MAAM,CAAC,OAAO,CAAC,EAAE,CAC3D,CAAC;QACN,CAAC;QACD,OAAO;YACH,EAAE,EAAE,GAAG,OAAO,mBAA0C;YACxD,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC;YAChC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ;YAC7B,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,WAAW;SACtC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAAkB;QAChC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC;QACnE,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,cAAc,CACpB,iDAAiD,OAAO,CAAC,QAAQ,EAAE,CACtE,CAAC;QACN,CAAC;QACD,OAAO,yBAAyB,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;CACJ;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,uBAAuB;IAChB,IAAI,GAA0B,EAAE,IAAI,EAAE,kBAAkB,EAAW,CAAC;IACnE,OAAO,CAA0B;IACjC,SAAS,CAA6B;IAEvD,YAAY,OAAgC;QACxC,IAAI,CAAC,OAAO,GAAG,IAAI,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,GAAG,IAAI,0BAA0B,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAED;;;;OAIG;IACH,IAAI,UAAU;QACV,OAAO,UAAU,CAAC;IACtB,CAAC;IAED,iBAAiB;QACb,wDAAwD;QACxD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,iBAAiB,EAAE,CAAC,EAAE,CAAC;YAC3F,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAkB,EAAE,GAAW;QACzC,IAAI,CAAC;YACD,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YAClB,MAAM,KAAK,GAAG,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YACvF,+DAA+D;YAC/D,IAAI,CAAC;gBACD,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACtD,CAAC;YAAC,OAAO,YAAY,EAAE,CAAC;gBACpB,MAAM,cAAc,GAAG,YAAY,YAAY,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;gBACtG,MAAM,IAAI,cAAc,CACpB,8BAA8B,MAAM,CAAC,OAAO,CAAC,qBAAqB,KAAK,CAAC,OAAO,wBAAwB,cAAc,CAAC,OAAO,GAAG,EAChI,EAAE,KAAK,EAAE,cAAc,EAAE,CAC5B,CAAC;YACN,CAAC;QACL,CAAC;IACL,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,OAAkB;QAChC,IAAI,CAAC;YACD,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YAClB,MAAM,KAAK,GAAG,UAAU,YAAY,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YACvF,IAAI,CAAC;gBACD,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YACrD,CAAC;YAAC,OAAO,YAAY,EAAE,CAAC;gBACpB,MAAM,cAAc,GAAG,YAAY,YAAY,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;gBACtG,MAAM,IAAI,cAAc,CACpB,gCAAgC,MAAM,CAAC,OAAO,CAAC,qBAAqB,KAAK,CAAC,OAAO,wBAAwB,cAAc,CAAC,OAAO,GAAG,EAClI,EAAE,KAAK,EAAE,cAAc,EAAE,CAC5B,CAAC;YACN,CAAC;QACL,CAAC;IACL,CAAC;CACJ;AAED;;;;GAIG;AACH,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAC;AAElD,sFAAsF;AACtF,MAAM,UAAU,uBAAuB,CACnC,IAA2B,EAC3B,OAAqD;IAErD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,kBAAkB;YACnB,OAAO,IAAI,uBAAuB,CAAC,OAA6C,CAAC,CAAC;QACtF,KAAK,cAAc;YACf,OAAO,IAAI,0BAA0B,CAAC,OAAyC,CAAC,CAAC;IACzF,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IAClE,OAAO,IAAI,uBAAuB,CAAC,OAAO,CAAC,CAAC;AAChD,CAAC;AAED,gEAAgE;AAChE,SAAS,eAAe,CAAC,OAAkB;IACvC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC1B,IAAI,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,aAAa,CAAC;IAClD,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,WAAW,CAAC;IAC/C,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,UAAU,CAAC;IAC5C,OAAO,YAAY,CAAC;AACxB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAc;IACnC,qEAAqE;IACrE,MAAM,MAAM,GAAG,iBAAiB,CAAC;IACjC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACrE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,cAAc,CAAC,6CAA6C,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,cAAc,CACpB,kDAAkD,GAAG,CAAC,MAAM,GAAG,CAClE,CAAC;IACN,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,SAAS,yBAAyB,CAAC,OAAsB;IACrD,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAEjD,uEAAuE;IACvE,2DAA2D;IAC3D,IAAI,IAAI,GAAsB,EAAE,CAAC;IACjC,IAAI,mBAAmB,GAAsB,EAAE,CAAC;IAChD,IAAI,cAAc,GAAsB,EAAE,CAAC;IAC3C,IAAI,CAAC;QACD,MAAM,IAAI,GAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAC1B,+DAA+D;YAC/D,uDAAuD;YACvD,KAAK,IAAI,CAAC;YACV,KAAK,IAAI,CAAC;YACV,KAAK,mBAAmB,CAAC;YACzB,KAAK,cAAc,CAAC;QACxB,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACL,8DAA8D;IAClE,CAAC;IAED,OAAO;QACH,GAAG;QACH,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,IAAI;QACJ,WAAW,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC;QACrC,eAAe,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,SAAS;QACjD,mBAAmB;QACnB,cAAc;KACjB,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAc;IACnC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACxC,CAAC"}

package/dist/rfc/rfcTests.d.ts

@@ -0,0 +1,14 @@
+/**
+ * RFC compliance test suites.
+ *
+ * Each function runs a focused compliance check and returns a {@link TestResult}.
+ * Stubbed until the underlying protocol stacks exist.
+ */
+import type { TestCaseId, TestResult } from "../types.js";
+/** Run the TLS 1.3 (RFC 8446) compliance checks. */
+export declare function runTlsCompliance(_id?: TestCaseId): TestResult;
+/** Run the HTTP/2 (RFC 9113) compliance checks. */
+export declare function runHttp2Compliance(_id?: TestCaseId): TestResult;
+/** Run the HTTP/1.1 (RFC 9110) compliance checks. */
+export declare function runHttp1Compliance(_id?: TestCaseId): TestResult;
+//# sourceMappingURL=rfcTests.d.ts.map

package/dist/rfc/rfcTests.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfcTests.d.ts","sourceRoot":"","sources":["../../src/rfc/rfcTests.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,oDAAoD;AACpD,wBAAgB,gBAAgB,CAC5B,GAAG,GAAE,UAAiC,GACvC,UAAU,CAGZ;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAC9B,GAAG,GAAE,UAAmC,GACzC,UAAU,CAGZ;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,CAC9B,GAAG,GAAE,UAAmC,GACzC,UAAU,CAGZ"}

package/dist/rfc/rfcTests.js

@@ -0,0 +1,22 @@
+/**
+ * RFC compliance test suites.
+ *
+ * Each function runs a focused compliance check and returns a {@link TestResult}.
+ * Stubbed until the underlying protocol stacks exist.
+ */
+/** Run the TLS 1.3 (RFC 8446) compliance checks. */
+export function runTlsCompliance(_id = "tls_rfc") {
+    void _id;
+    throw new Error("not implemented — see PLAN.md");
+}
+/** Run the HTTP/2 (RFC 9113) compliance checks. */
+export function runHttp2Compliance(_id = "http2_rfc") {
+    void _id;
+    throw new Error("not implemented — see PLAN.md");
+}
+/** Run the HTTP/1.1 (RFC 9110) compliance checks. */
+export function runHttp1Compliance(_id = "http1_rfc") {
+    void _id;
+    throw new Error("not implemented — see PLAN.md");
+}
+//# sourceMappingURL=rfcTests.js.map

package/dist/rfc/rfcTests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfcTests.js","sourceRoot":"","sources":["../../src/rfc/rfcTests.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,oDAAoD;AACpD,MAAM,UAAU,gBAAgB,CAC5B,MAAmB,SAAmB;IAEtC,KAAK,GAAG,CAAC;IACT,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;AACrD,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,kBAAkB,CAC9B,MAAmB,WAAqB;IAExC,KAAK,GAAG,CAAC;IACT,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;AACrD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB,CAC9B,MAAmB,WAAqB;IAExC,KAAK,GAAG,CAAC;IACT,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;AACrD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Domain types for @browsercore/testing.
+ *
+ * Protocol verification: RFC compliance tests, browser golden packet captures,
+ * integration tests, and benchmarking. Compares generated packets against
+ * captures from real browsers.
+ */
+/** Branded test-case identifier. */
+export type TestCaseId = string & {
+    __brand: "TestCaseId";
+};
+/** Branded golden-capture identifier. */
+export type CaptureId = string & {
+    __brand: "CaptureId";
+};
+/** Known browser capture sources. */
+export type CaptureSource = "chrome-140" | "firefox-135" | "safari-18" | "edge-140";
+/** Which protocol layer a capture records. */
+export type CaptureProtocol = "tls" | "http2" | "http1" | "tcp";
+/** A single runnable test case. */
+export interface TestCase {
+    readonly id: TestCaseId;
+    readonly name: string;
+    readonly description: string;
+    run(): Promise<TestResult>;
+}
+/** Outcome of running a single {@link TestCase}. */
+export interface TestResult {
+    readonly id: TestCaseId;
+    readonly pass: boolean;
+    /** Actual bytes / value produced. */
+    readonly actual: unknown;
+    /** Expected bytes / value. */
+    readonly expected: unknown;
+    /** Human-readable diff when `pass === false`. */
+    readonly diff?: string;
+}
+/** A golden packet capture recorded from a real browser. */
+export interface GoldenCapture {
+    readonly id: CaptureId;
+    readonly source: CaptureSource;
+    readonly protocol: CaptureProtocol;
+    /** Raw bytes as seen on the wire. */
+    readonly bytes: Uint8Array;
+    readonly description: string;
+}
+/** Result of comparing actual bytes against a golden capture. */
+export interface ComparisonResult {
+    readonly matches: boolean;
+    /** First byte index where actual diverges from expected, if any. */
+    readonly divergenceByteIndex: number | undefined;
+    readonly message: string;
+}
+/** Summary statistics for a benchmark run. */
+export interface BenchStats {
+    readonly iterations: number;
+    readonly avgMs: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly p99: number;
+}
+/**
+ * The 17 test categories from docs/TEST-SUITE.md.
+ *
+ * Defined as a `const` object so the id set is the single source of truth and
+ * `TestCategoryId` is derived from it — never a bare string (see
+ * CODING_STANDARDS.md §17 "No magic strings").
+ */
+export declare const TestCategory: {
+    readonly TcpTransport: "tcp-transport";
+    readonly TlsSerialization: "tls-serialization";
+    readonly BrowserProfileComparison: "browser-profile-comparison";
+    readonly TlsFingerprint: "tls-fingerprint";
+    readonly Http1: "http1";
+    readonly Http2: "http2";
+    readonly HeaderProfiles: "header-profiles";
+    readonly CookieBehavior: "cookie-behavior";
+    readonly Compression: "compression";
+    readonly RedirectHandling: "redirect-handling";
+    readonly SessionResumption: "session-resumption";
+    readonly ConnectionReuse: "connection-reuse";
+    readonly ErrorHandling: "error-handling";
+    readonly PacketCaptureComparison: "packet-capture-comparison";
+    readonly RealWorldCompatibility: "real-world-compatibility";
+    readonly Regression: "regression";
+    readonly PerformanceBenchmarks: "performance-benchmarks";
+};
+/** One of the 17 known test-category ids. */
+export type TestCategoryId = (typeof TestCategory)[keyof typeof TestCategory];
+/** Lifecycle status of a spec test case in the plan. */
+export type TestStatus = "planned" | "implemented" | "skipped";
+/**
+ * A single test case as recorded in the spec plan.
+ *
+ * Distinct from the runnable {@link TestCase} interface (which carries a
+ * `run()` method); this is a static plan/record entry.
+ */
+export interface SpecTestCase {
+    readonly id: TestCaseId;
+    readonly category: TestCategoryId;
+    readonly name: string;
+    readonly description: string;
+    readonly status: TestStatus;
+}
+/** A recorded run of spec test cases plus their outcomes. */
+export interface TestRun {
+    readonly id: string;
+    readonly timestamp: string;
+    readonly cases: readonly SpecTestCase[];
+}
+/**
+ * A byte range within a capture that is intentionally randomized by the
+ * protocol spec and so MUST be masked before golden comparison (Cat 14).
+ */
+export interface RandomizedField {
+    readonly byteOffset: number;
+    readonly length: number;
+    readonly reason: "ephemeral_key" | "nonce" | "grease" | "random";
+}
+/** Metadata describing a stored golden capture (sidecar to its `.bin`). */
+export interface CaptureMeta {
+    readonly source: "curl-impersonate" | "real-browser";
+    readonly profile: import("@browsercore/profiles").ProfileId;
+    readonly protocol: CaptureProtocol;
+    readonly record: "client_hello" | "settings" | "headers" | "server_hello";
+    readonly description: string;
+    readonly randomizedFields: readonly RandomizedField[];
+    readonly createdAt: string;
+}
+/**
+ * Result of a byte comparison that supports an ignore-list of randomized
+ * ranges. Extends {@link ComparisonResult} with the ranges that were masked.
+ */
+export interface ComparisonResultWithIgnore {
+    readonly matches: boolean;
+    readonly divergenceByteIndex: number | undefined;
+    readonly message: string;
+    readonly maskedRanges: readonly RandomizedField[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,34 @@
+/**
+ * Domain types for @browsercore/testing.
+ *
+ * Protocol verification: RFC compliance tests, browser golden packet captures,
+ * integration tests, and benchmarking. Compares generated packets against
+ * captures from real browsers.
+ */
+/**
+ * The 17 test categories from docs/TEST-SUITE.md.
+ *
+ * Defined as a `const` object so the id set is the single source of truth and
+ * `TestCategoryId` is derived from it — never a bare string (see
+ * CODING_STANDARDS.md §17 "No magic strings").
+ */
+export const TestCategory = {
+    TcpTransport: "tcp-transport",
+    TlsSerialization: "tls-serialization",
+    BrowserProfileComparison: "browser-profile-comparison",
+    TlsFingerprint: "tls-fingerprint",
+    Http1: "http1",
+    Http2: "http2",
+    HeaderProfiles: "header-profiles",
+    CookieBehavior: "cookie-behavior",
+    Compression: "compression",
+    RedirectHandling: "redirect-handling",
+    SessionResumption: "session-resumption",
+    ConnectionReuse: "connection-reuse",
+    ErrorHandling: "error-handling",
+    PacketCaptureComparison: "packet-capture-comparison",
+    RealWorldCompatibility: "real-world-compatibility",
+    Regression: "regression",
+    PerformanceBenchmarks: "performance-benchmarks",
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB,YAAY,EAAE,eAAe;IAC7B,gBAAgB,EAAE,mBAAmB;IACrC,wBAAwB,EAAE,4BAA4B;IACtD,cAAc,EAAE,iBAAiB;IACjC,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,cAAc,EAAE,iBAAiB;IACjC,cAAc,EAAE,iBAAiB;IACjC,WAAW,EAAE,aAAa;IAC1B,gBAAgB,EAAE,mBAAmB;IACrC,iBAAiB,EAAE,oBAAoB;IACvC,eAAe,EAAE,kBAAkB;IACnC,aAAa,EAAE,gBAAgB;IAC/B,uBAAuB,EAAE,2BAA2B;IACpD,sBAAsB,EAAE,0BAA0B;IAClD,UAAU,EAAE,YAAY;IACxB,qBAAqB,EAAE,wBAAwB;CACzC,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Small shared helpers for @browsercore/testing.
+ */
+import type { ComparisonResult, ComparisonResultWithIgnore, RandomizedField } from "./types.js";
+/**
+ * Exhaustiveness check for `switch`/`if-else` over discriminated unions.
+ * Call in the `default` branch: `default: assertNever(x)`.
+ * Adding a new union member forces every handler to compile-error until handled.
+ */
+export declare function assertNever(x: never): never;
+/** Generate a unique TestCaseId (not cryptographically random). */
+export declare function createId(prefix?: "tc"): string;
+/** Format bytes as a lowercase hex string with no separators. */
+export declare function bytesToHex(buf: Uint8Array): string;
+/**
+ * Compare two byte arrays. Returns a {@link ComparisonResult} reporting whether
+ * they match, the first divergence index (if any), and a message.
+ */
+export declare function compareBytes(a: Uint8Array, b: Uint8Array): ComparisonResult;
+/**
+ * Compare two byte arrays while masking byte ranges that are intentionally
+ * randomized by the protocol spec (ephemeral keys, nonces, GREASE, random).
+ *
+ * Ranges in `ignore` are skipped when scanning for divergence. The returned
+ * {@link ComparisonResultWithIgnore.maskedReports} lists the ranges that were
+ * masked so callers can audit what was excluded.
+ */
+export declare function compareBytesWithIgnore(a: Uint8Array, b: Uint8Array, ignore: readonly RandomizedField[]): ComparisonResultWithIgnore;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACR,gBAAgB,EAChB,0BAA0B,EAC1B,eAAe,EAClB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AAEH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAE3C;AAED,mEAAmE;AACnE,wBAAgB,QAAQ,CAAC,MAAM,GAAE,IAAW,GAAG,MAAM,CAEpD;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAMlD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAsB3E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAClC,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,UAAU,EACb,MAAM,EAAE,SAAS,eAAe,EAAE,GACnC,0BAA0B,CAwC5B"}