@browsercore/testing 0.1.3 → 0.2.1

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/reference/browser-provider.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SECONDARY reference provider — loads pre-recorded captures from `captures/`.
+ *
+ * `capture()` resolves a stored capture for the profile; `fingerprint()`
+ * derives a {@link Fingerprint} from the captured bytes (only TLS ClientHellos
+ * are fingerprinted — other protocols throw). Split out of `reference.ts` so
+ * the facade stays focused on primary → secondary dispatch.
+ */
+import type { ProfileId } from "@browsercore/profiles";
+import type { GoldenCapture } from "../types.js";
+import type { Fingerprint, ReferenceProvider, ReferenceProviderKind } from "./reference-types.js";
+/** Options for the real-browser (pre-recorded capture) provider. */
+export interface RealBrowserOptions {
+    readonly command?: undefined;
+    /** Override captures directory. Defaults to the in-repo `captures/` dir. */
+    readonly capturesDir?: string;
+}
+/**
+ * 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 declare class RealBrowserCaptureProvider implements ReferenceProvider {
+    readonly kind: ReferenceProviderKind;
+    readonly capturesDir: string;
+    constructor(options?: RealBrowserOptions);
+    availableProfiles(): ProfileId[];
+    capture(profile: ProfileId, _url: string): Promise<GoldenCapture>;
+    fingerprint(profile: ProfileId): Promise<Fingerprint>;
+}
+//# sourceMappingURL=browser-provider.d.ts.map

package/dist/reference/browser-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-provider.d.ts","sourceRoot":"","sources":["../../src/reference/browser-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlG,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,qBAAa,0BAA2B,YAAW,iBAAiB;IAChE,SAAgB,IAAI,EAAE,qBAAqB,CAAqC;IAChF,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC,YAAY,OAAO,CAAC,EAAE,kBAAkB,EAEvC;IAED,iBAAiB,IAAI,SAAS,EAAE,CAM/B;IAEK,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgBtE;IAEK,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAQ1D;CACJ"}

package/dist/reference/browser-provider.js

@@ -0,0 +1,61 @@
+/**
+ * SECONDARY reference provider — loads pre-recorded captures from `captures/`.
+ *
+ * `capture()` resolves a stored capture for the profile; `fingerprint()`
+ * derives a {@link Fingerprint} from the captured bytes (only TLS ClientHellos
+ * are fingerprinted — other protocols throw). Split out of `reference.ts` so
+ * the facade stays focused on primary → secondary dispatch.
+ */
+import { ReferenceError } from "./reference-errors.js";
+import { fingerprintFromTlsCapture, profileToSource } from "./dump.js";
+import { createPath } from "../node-provider.js";
+const path = createPath();
+/**
+ * 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);
+    }
+}
+// Default captures dir resolved from this module's location. Computed at module
+// load (not per-instance) since import.meta.dirname is static.
+const here = import.meta.dirname;
+const packageRoot = path.join(here, "..", "..");
+const defaultCapturesDir = path.join(packageRoot, "captures");
+//# sourceMappingURL=browser-provider.js.map

package/dist/reference/browser-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-provider.js","sourceRoot":"","sources":["../../src/reference/browser-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;AAS1B;;;;;;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,gFAAgF;AAChF,+DAA+D;AAC/D,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,OAAO,CAAC;AACjC,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAChD,MAAM,kBAAkB,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC"}

package/dist/reference/curl-provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * PRIMARY reference 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.
+ *
+ * Split out of `reference.ts` so the facade module stays focused on primary →
+ * secondary dispatch while this file owns the curl-impersonate subprocess
+ * wiring and dump-format parsing.
+ */
+import type { ProfileId } from "@browsercore/profiles";
+import type { GoldenCapture } from "../types.js";
+import type { Fingerprint, ReferenceProvider, ReferenceProviderKind } from "./reference-types.js";
+/** Options for the curl-impersonate provider. */
+export interface CurlImpersonateOptions {
+    /** Path / name of the curl-impersonate binary. Default "curl-impersonate". */
+    readonly command: string;
+    /** Extra argv passed to the binary. */
+    readonly extraArgs?: readonly string[];
+}
+/**
+ * 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 declare class CurlImpersonateProvider implements ReferenceProvider {
+    readonly kind: ReferenceProviderKind;
+    readonly command: string;
+    readonly extraArgs: readonly string[];
+    constructor(options?: CurlImpersonateOptions);
+    availableProfiles(): ProfileId[];
+    capture(profile: ProfileId, url: string): Promise<GoldenCapture>;
+    fingerprint(profile: ProfileId): Promise<Fingerprint>;
+}
+//# sourceMappingURL=curl-provider.d.ts.map

package/dist/reference/curl-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"curl-provider.d.ts","sourceRoot":"","sources":["../../src/reference/curl-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlG,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAiCD;;;;;;;GAOG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC7D,SAAgB,IAAI,EAAE,qBAAqB,CAAyC;IACpF,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,SAAgB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C,YAAY,OAAO,CAAC,EAAE,sBAAsB,EAG3C;IAED,iBAAiB,IAAI,SAAS,EAAE,CAU/B;IAEK,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BrE;IAEK,WAAW,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAG1D;CACJ"}

package/dist/reference/curl-provider.js

@@ -0,0 +1,96 @@
+/**
+ * PRIMARY reference 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.
+ *
+ * Split out of `reference.ts` so the facade module stays focused on primary →
+ * secondary dispatch while this file owns the curl-impersonate subprocess
+ * wiring and dump-format parsing.
+ */
+import { execFile, } from "node:child_process";
+import { ReferenceError } from "./reference-errors.js";
+import { fingerprintFromTlsCapture, parseDumpOutput, profileToSource } from "./dump.js";
+/**
+ * Run `command args...` and resolve its captured `{stdout, stderr}`.
+ *
+ * Wraps node:child_process `execFile` with a `Promise` rather than
+ * `util.promisify` so the types resolve without forcing casts — `execFile`'s
+ * overloads return `ChildProcess`, which `promisify` cannot infer a useful
+ * promise type from. Rejects with an `ExecFileException`-shaped `Error` on
+ * non-zero exit, timeout, or spawn failure.
+ */
+function runExecFile(command, args, options) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, options, (err, stdout, stderr) => {
+            if (err !== null) {
+                reject(err);
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}
+/**
+ * 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 runExecFile(this.command, args, {
+                timeout: 30_000,
+                maxBuffer: 64 * 1024 * 1024,
+                encoding: "utf8",
+            });
+            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);
+    }
+}
+//# sourceMappingURL=curl-provider.js.map

package/dist/reference/curl-provider.js.map

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

package/dist/reference/dump.d.ts

@@ -0,0 +1,42 @@
+/**
+ * curl-impersonate dump parsing + TLS fingerprint derivation.
+ *
+ * Split out of `reference.ts` so the providers and facade stay focused on
+ * dispatch while this file owns the curl-impersonate `--dump-traffic` byte
+ * format and the JA3/JA4 derivation from a captured ClientHello.
+ */
+import type { ProfileId } from "@browsercore/profiles";
+import type { GoldenCapture } from "../types.js";
+import type { Fingerprint } from "./reference-types.js";
+/** Map a {@link ProfileId} to its {@link CaptureSource} tag. */
+export declare function profileToSource(profile: ProfileId): GoldenCapture["source"];
+/**
+ * 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 after the `>>> traffic <<<` marker. Throws {@link DumpParseError}
+ * when no hex bytes follow the marker or the hex has odd length.
+ */
+export declare function parseDumpOutput(stdout: string): Uint8Array;
+/**
+ * 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.
+ *
+ * Exported for unit testing the try/catch branches: the happy path reads the
+ * sidecar meta, while the fallback path is taken when the sidecar is missing.
+ */
+export declare function fingerprintFromTlsCapture(capture: GoldenCapture): Fingerprint;
+/**
+ * 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.
+ *
+ * Exported for unit testing the empty-tag fallback branch.
+ */
+export declare function cipherSuiteName(ja4Tag: string): string;
+//# sourceMappingURL=dump.d.ts.map

package/dist/reference/dump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dump.d.ts","sourceRoot":"","sources":["../../src/reference/dump.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,OAAO,EAAE,SAAS,GAAG,aAAa,CAAC,QAAQ,CAAC,CAY3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAiB1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CA6B7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD"}

package/dist/reference/dump.js

@@ -0,0 +1,102 @@
+/**
+ * curl-impersonate dump parsing + TLS fingerprint derivation.
+ *
+ * Split out of `reference.ts` so the providers and facade stay focused on
+ * dispatch while this file owns the curl-impersonate `--dump-traffic` byte
+ * format and the JA3/JA4 derivation from a captured ClientHello.
+ */
+import { computeJa3, computeJa4Fingerprint } from "../fingerprint/index.js";
+import { loadCaptureMeta } from "../golden/golden.js";
+import { DumpParseError } from "./reference-errors.js";
+/** Map a {@link ProfileId} to its {@link CaptureSource} tag. */
+export 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 after the `>>> traffic <<<` marker. Throws {@link DumpParseError}
+ * when no hex bytes follow the marker or the hex has odd length.
+ */
+export 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.replaceAll(/[^0-9a-fA-F]/gu, "");
+    if (hex.length === 0) {
+        throw new DumpParseError("no_hex", 0);
+    }
+    if (hex.length % 2 !== 0) {
+        throw new DumpParseError("odd_length", 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.
+ *
+ * Exported for unit testing the try/catch branches: the happy path reads the
+ * sidecar meta, while the fallback path is taken when the sidecar is missing.
+ */
+export 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.
+    const alpn = [];
+    const signatureAlgorithms = [];
+    const 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;
+        }
+    }
+    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.
+ *
+ * Exported for unit testing the empty-tag fallback branch.
+ */
+export function cipherSuiteName(ja4Tag) {
+    const a = ja4Tag.split("_")[0] ?? "";
+    return a.length > 0 ? a : "unknown";
+}
+//# sourceMappingURL=dump.js.map

package/dist/reference/dump.js.map

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

package/dist/reference/node-crypto-provider.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Local Node-backed CryptoProvider double.
+ *
+ * @browsercore/crypto 0.2.2 exports only types, errors, and utilities — the
+ * runtime NodeCryptoProvider implementation lives in
+ * `browsersmith/src/platform/crypto/node/`. This repo (Layer 4) cannot depend
+ * on browsersmith (Layer 5), so we provide a local Node-backed implementation
+ * of the `CryptoProvider` contract for tests and e2e harnesses.
+ *
+ * This double mirrors the production NodeCryptoProvider behavior:
+ * - Hashing via node:crypto (sha256, sha384)
+ * - HKDF via node:crypto.hkdfSync
+ * - HMAC via node:crypto.createHmac
+ * - AEAD via node:crypto.createCipheriv/createDecipheriv (GCM, CCM, ChaCha20)
+ * - X25519 via NobleX25519Backend (pure JS, no native binding)
+ * - ECDH via node:crypto.ECDH
+ * - Signatures via node:crypto.createVerify
+ * - Random bytes via node:crypto.randomBytes
+ *
+ * The production provider uses the same primitives — this double exists only
+ * because the package boundary moved the implementation to a higher layer.
+ */
+import type { CryptoProvider } from "@browsercore/crypto";
+/**
+ * Node-backed CryptoProvider implementation.
+ *
+ * Satisfies the full `CryptoProvider` contract using node:crypto + noble-curves.
+ * Safe for tests and e2e harnesses — never imported by production protocol code.
+ */
+export declare const nodeCryptoProvider: CryptoProvider;
+//# sourceMappingURL=node-crypto-provider.d.ts.map

package/dist/reference/node-crypto-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-crypto-provider.d.ts","sourceRoot":"","sources":["../../src/reference/node-crypto-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH,OAAO,KAAK,EACR,cAAc,EAKjB,MAAM,qBAAqB,CAAC;AAgC7B;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAsJhC,CAAC"}

package/dist/reference/node-crypto-provider.js

@@ -0,0 +1,199 @@
+/**
+ * Local Node-backed CryptoProvider double.
+ *
+ * @browsercore/crypto 0.2.2 exports only types, errors, and utilities — the
+ * runtime NodeCryptoProvider implementation lives in
+ * `browsersmith/src/platform/crypto/node/`. This repo (Layer 4) cannot depend
+ * on browsersmith (Layer 5), so we provide a local Node-backed implementation
+ * of the `CryptoProvider` contract for tests and e2e harnesses.
+ *
+ * This double mirrors the production NodeCryptoProvider behavior:
+ * - Hashing via node:crypto (sha256, sha384)
+ * - HKDF via node:crypto.hkdfSync
+ * - HMAC via node:crypto.createHmac
+ * - AEAD via node:crypto.createCipheriv/createDecipheriv (GCM, CCM, ChaCha20)
+ * - X25519 via NobleX25519Backend (pure JS, no native binding)
+ * - ECDH via node:crypto.ECDH
+ * - Signatures via node:crypto.createVerify
+ * - Random bytes via node:crypto.randomBytes
+ *
+ * The production provider uses the same primitives — this double exists only
+ * because the package boundary moved the implementation to a higher layer.
+ */
+import { createCipheriv, createDecipheriv, createECDH, createHash, createHmac, createVerify, hkdfSync, randomBytes, } from "node:crypto";
+import { NobleX25519Backend } from "@browsercore/crypto";
+const noble = new NobleX25519Backend();
+/** Curve → node:crypto named curve + expected coordinate length. */
+const ECDH_CURVE_PARAMS = {
+    secp256r1: { nodeCurve: "prime256v1", coordLen: 32 },
+    secp384r1: { nodeCurve: "secp384r1", coordLen: 48 },
+};
+/** Map our HashId branded union to node:crypto's hash algorithm name. */
+function hashName(hash) {
+    return hash === "SHA-256" ? "sha256" : "sha384";
+}
+/**
+ * Convert a Uint8Array to a node Buffer for cipher APIs.
+ * Newer @types/node BinaryLike excludes bare ArrayBuffer — Buffer is always safe.
+ */
+function toBuf(data) {
+    return Buffer.from(data);
+}
+/**
+ * Map a 12-byte AEAD nonce to a node:crypto IV (Buffer).
+ * Used uniformly by every AEAD path so the conversion happens in one place.
+ */
+function toIv(nonce) {
+    return Buffer.from(nonce);
+}
+/**
+ * Node-backed CryptoProvider implementation.
+ *
+ * Satisfies the full `CryptoProvider` contract using node:crypto + noble-curves.
+ * Safe for tests and e2e harnesses — never imported by production protocol code.
+ */
+export const nodeCryptoProvider = {
+    randomBytes(length) {
+        return new Uint8Array(randomBytes(length));
+    },
+    sha256(data) {
+        return new Uint8Array(createHash("sha256").update(toBuf(data)).digest());
+    },
+    sha384(data) {
+        return new Uint8Array(createHash("sha384").update(toBuf(data)).digest());
+    },
+    hkdf(hash, salt, ikm, info, length) {
+        return new Uint8Array(hkdfSync(hashName(hash), toBuf(ikm), toBuf(salt), toBuf(info), length));
+    },
+    hmac(hash, key, data) {
+        return new Uint8Array(createHmac(hashName(hash), toBuf(key)).update(toBuf(data)).digest());
+    },
+    aes128GcmEncrypt(key, nonce, plaintext, aad) {
+        const cipher = createCipheriv("aes-128-gcm", toBuf(key), toIv(nonce));
+        cipher.setAAD(toBuf(aad));
+        const ciphertext = Buffer.concat([cipher.update(toBuf(plaintext)), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return new Uint8Array(Buffer.concat([ciphertext, tag]));
+    },
+    aes128GcmDecrypt(key, nonce, ciphertext, aad) {
+        const tagLen = 16;
+        const enc = ciphertext.subarray(0, ciphertext.length - tagLen);
+        const tag = ciphertext.subarray(ciphertext.length - tagLen);
+        const decipher = createDecipheriv("aes-128-gcm", toBuf(key), toIv(nonce));
+        decipher.setAuthTag(toBuf(tag));
+        decipher.setAAD(toBuf(aad));
+        return new Uint8Array(Buffer.concat([decipher.update(toBuf(enc)), decipher.final()]));
+    },
+    aes256GcmEncrypt(key, nonce, plaintext, aad) {
+        const cipher = createCipheriv("aes-256-gcm", toBuf(key), toIv(nonce));
+        cipher.setAAD(toBuf(aad));
+        const ciphertext = Buffer.concat([cipher.update(toBuf(plaintext)), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return new Uint8Array(Buffer.concat([ciphertext, tag]));
+    },
+    aes256GcmDecrypt(key, nonce, ciphertext, aad) {
+        const tagLen = 16;
+        const enc = ciphertext.subarray(0, ciphertext.length - tagLen);
+        const tag = ciphertext.subarray(ciphertext.length - tagLen);
+        const decipher = createDecipheriv("aes-256-gcm", toBuf(key), toIv(nonce));
+        decipher.setAuthTag(toBuf(tag));
+        decipher.setAAD(toBuf(aad));
+        return new Uint8Array(Buffer.concat([decipher.update(toBuf(enc)), decipher.final()]));
+    },
+    aes128CcmEncrypt(key, nonce, plaintext, aad) {
+        const cipher = createCipheriv("aes-128-ccm", toBuf(key), toIv(nonce), {
+            authTagLength: 16,
+        });
+        cipher.setAAD(toBuf(aad), { plaintextLength: plaintext.length });
+        const ciphertext = Buffer.concat([cipher.update(toBuf(plaintext)), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return new Uint8Array(Buffer.concat([ciphertext, tag]));
+    },
+    aes128CcmDecrypt(key, nonce, ciphertext, aad) {
+        const tagLen = 16;
+        const enc = ciphertext.subarray(0, ciphertext.length - tagLen);
+        const tag = ciphertext.subarray(ciphertext.length - tagLen);
+        const decipher = createDecipheriv("aes-128-ccm", toBuf(key), toIv(nonce), {
+            authTagLength: 16,
+        });
+        decipher.setAuthTag(toBuf(tag));
+        decipher.setAAD(toBuf(aad), { plaintextLength: enc.length });
+        return new Uint8Array(Buffer.concat([decipher.update(toBuf(enc)), decipher.final()]));
+    },
+    chacha20Poly1305Encrypt(key, nonce, plaintext, aad) {
+        const cipher = createCipheriv("chacha20-poly1305", toBuf(key), toIv(nonce), {
+            authTagLength: 16,
+        });
+        cipher.setAAD(toBuf(aad));
+        const ciphertext = Buffer.concat([cipher.update(toBuf(plaintext)), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return new Uint8Array(Buffer.concat([ciphertext, tag]));
+    },
+    chacha20Poly1305Decrypt(key, nonce, ciphertext, aad) {
+        const tagLen = 16;
+        const enc = ciphertext.subarray(0, ciphertext.length - tagLen);
+        const tag = ciphertext.subarray(ciphertext.length - tagLen);
+        const decipher = createDecipheriv("chacha20-poly1305", toBuf(key), toIv(nonce), {
+            authTagLength: 16,
+        });
+        decipher.setAuthTag(toBuf(tag));
+        decipher.setAAD(toBuf(aad));
+        return new Uint8Array(Buffer.concat([decipher.update(toBuf(enc)), decipher.final()]));
+    },
+    x25519GenerateKeyPair() {
+        const secretKey = this.randomBytes(32);
+        const publicKey = noble.publicKey(secretKey);
+        return { publicKey, secretKey };
+    },
+    x25519SharedSecret(secretKey, peerPublicKey) {
+        return noble.sharedSecret(secretKey, peerPublicKey);
+    },
+    ecdhGenerateKeyPair(curve) {
+        const params = ECDH_CURVE_PARAMS[curve];
+        const ecdh = createECDH(params.nodeCurve);
+        ecdh.generateKeys();
+        const publicKey = ecdh.getPublicKey(null, "uncompressed");
+        const secretKey = ecdh.getPrivateKey();
+        return {
+            curve,
+            publicKey: new Uint8Array(publicKey),
+            secretKey: new Uint8Array(secretKey),
+        };
+    },
+    ecdhSharedSecret(curve, secretKey, peerPublicKey) {
+        const params = ECDH_CURVE_PARAMS[curve];
+        const ecdh = createECDH(params.nodeCurve);
+        ecdh.setPrivateKey(toBuf(secretKey));
+        const shared = ecdh.computeSecret(toBuf(peerPublicKey));
+        return new Uint8Array(shared.subarray(shared.length - params.coordLen));
+    },
+    verifySignature(scheme, publicKey, signature, data) {
+        const verifier = createVerify(verificationHash(scheme));
+        verifier.update(toBuf(data));
+        return verifier.verify({ key: toBuf(publicKey), format: "der", type: "spki" }, toBuf(signature));
+    },
+    aesEcbEncrypt(key, block) {
+        const cipher = createCipheriv(key.length === 16 ? "aes-128-ecb" : "aes-256-ecb", toBuf(key), null);
+        cipher.setAutoPadding(false);
+        return new Uint8Array(cipher.update(toBuf(block)));
+    },
+};
+/**
+ * Map a TLS signature-scheme name to a node:crypto verification hash.
+ * Only the schemes the test suite exercises are covered.
+ */
+function verificationHash(scheme) {
+    switch (scheme) {
+        case "ecdsa_secp256r1_sha256":
+        case "rsa_pss_rsae_sha256":
+        case "rsa_pkcs1_sha256":
+            return "sha256";
+        case "ecdsa_secp384r1_sha384":
+        case "rsa_pss_rsae_sha384":
+        case "rsa_pkcs1_sha384":
+            return "sha384";
+        default:
+            return "sha256";
+    }
+}
+//# sourceMappingURL=node-crypto-provider.js.map