@rester159/blacktip 0.2.0 → 0.5.0

package/dist/index.d.ts

@@ -8,14 +8,23 @@ export { Logger } from './logging.js';
 export { BrowserCore } from './browser-core.js';
 export { fitDistribution, fitFittsLaw, fitMouseDynamics, fitTypingDynamics, fitFromSamples, deriveProfileConfig, } from './behavioral/calibration.js';
 export type { MouseSample, MouseMovement, KeystrokeSample, TypingSession, DistributionFit, MouseFit, TypingFit, CalibratedProfile, } from './behavioral/calibration.js';
+export { parseCmuKeystrokeCsv, parseBalabitMouseCsv, parseGenericTelemetryJson, CMU_PHRASE, } from './behavioral/parsers.js';
+export { TlsSideChannel } from './tls-side-channel.js';
+export type { TlsRequest, TlsResponse, ParsedCookie } from './tls-side-channel.js';
+export { installTlsRewriter } from './tls-rewriter.js';
+export type { TlsRewriterOptions, TlsRewriterStats } from './tls-rewriter.js';
+export { solveAkamaiChallenge, parseAbckState } from './akamai-sensor.js';
+export type { AkamaiChallengeResult } from './akamai-sensor.js';
+export { IdentityPool } from './identity-pool.js';
+export type { Identity, IdentityPoolOptions, RotationPolicy, DeviceProfileName, } from './identity-pool.js';
 export { ProxyPool, ProxyProviders, proxyToUrl } from './proxy-pool.js';
 export type { ProxyDescriptor, ProxyProtocol, PoolOptions } from './proxy-pool.js';
 export { SnapshotManager } from './snapshot.js';
 export type { SessionSnapshot } from './snapshot.js';
 export { attachObservability, JsonlFileExporter, ConsoleExporter, newTraceId, } from './observability.js';
 export type { StructuredEvent, EventExporter } from './observability.js';
-export { captureFingerprint, checkIpReputation, testAgainstAkamai, } from './diagnostics.js';
-export type { FingerprintSnapshot, IpReputationResult, AkamaiTestResult, } from './diagnostics.js';
+export { captureFingerprint, checkIpReputation, testAgainstAkamai, testAgainstAntiBot, } from './diagnostics.js';
+export type { FingerprintSnapshot, IpReputationResult, AkamaiTestResult, AntiBotTestResult, AntiBotVendor, } from './diagnostics.js';
 export type { BlackTipConfig, ProfileConfig, DeviceProfile, PluginData, ActionResult, NavigateResult, ScreenshotResult, WaitResult, ActionEvent, BehavioralMetadata, ErrorEvent, RetryEvent, TabChangeEvent, LogEntry, TabInfo, FrameInfo, LogLevel, ClickOptions, TypeOptions, ScrollOptions, HoverOptions, SelectOptions, PressKeyOptions, UploadFileOptions, NavigateOptions, ScreenshotOptions, WaitForOptions, WaitForNavigationOptions, ExtractTextOptions, PageContentOptions, ErrorCode, RetryStrategy, Point, BoundingBox, } from './types.js';
 export { ErrorCodes } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC1F,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EACL,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,EACf,QAAQ,EACR,SAAS,EACT,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGzE,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,cAAc,EACd,QAAQ,EACR,OAAO,EACP,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,KAAK,EACL,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -7,10 +7,20 @@ export { Logger } from './logging.js';
 export { BrowserCore } from './browser-core.js';
 // v2 additions — Tier 2 calibration, Tier 3 infrastructure, observability.
 export { fitDistribution, fitFittsLaw, fitMouseDynamics, fitTypingDynamics, fitFromSamples, deriveProfileConfig, } from './behavioral/calibration.js';
+// v0.3.0 — dataset parsers for end-to-end calibration
+export { parseCmuKeystrokeCsv, parseBalabitMouseCsv, parseGenericTelemetryJson, CMU_PHRASE, } from './behavioral/parsers.js';
+// v0.3.0 — TLS side-channel via bogdanfinn/tls-client
+export { TlsSideChannel } from './tls-side-channel.js';
+// v0.5.0 — full TLS rewriting via CDP Fetch interception + Go daemon
+export { installTlsRewriter } from './tls-rewriter.js';
+// v0.5.0 — Akamai sensor challenge solver
+export { solveAkamaiChallenge, parseAbckState } from './akamai-sensor.js';
+// v0.4.0 — IdentityPool: long-running session and identity rotation
+export { IdentityPool } from './identity-pool.js';
 export { ProxyPool, ProxyProviders, proxyToUrl } from './proxy-pool.js';
 export { SnapshotManager } from './snapshot.js';
 export { attachObservability, JsonlFileExporter, ConsoleExporter, newTraceId, } from './observability.js';
 // v0.2.0 — stealth diagnostics
-export { captureFingerprint, checkIpReputation, testAgainstAkamai, } from './diagnostics.js';
+export { captureFingerprint, checkIpReputation, testAgainstAkamai, testAgainstAntiBot, } from './diagnostics.js';
 export { ErrorCodes } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,2EAA2E;AAC3E,OAAO,EACL,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAYrC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGxE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,+BAA+B;AAC/B,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AA4C1B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,2EAA2E;AAC3E,OAAO,EACL,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAYrC,sDAAsD;AACtD,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,yBAAyB,EACzB,UAAU,GACX,MAAM,yBAAyB,CAAC;AAEjC,sDAAsD;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,qEAAqE;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGvD,0CAA0C;AAC1C,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAG1E,oEAAoE;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAQlD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGxE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAG5B,+BAA+B;AAC/B,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AA8C1B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/tls-rewriter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * TLS rewriting via CDP Fetch interception.
+ *
+ * The v0.5.0 answer to "every wire request should present a real Chrome
+ * TLS fingerprint, not just the gating ones." Without a TCP-level MITM
+ * proxy (and the OS-specific cert installation hell that entails), we
+ * use Chrome DevTools Protocol's `Fetch.enable` to pause every HTTP
+ * request the browser issues, hand it to the Go `bogdanfinn/tls-client`
+ * daemon for upstream execution, and fulfill the response back through
+ * CDP. The browser never opens an upstream TCP connection — all its
+ * HTTP is fulfilled by us.
+ *
+ * Patchright/Playwright expose this as `context.route('**', handler)`,
+ * which is the high-level wrapper around CDP Fetch. We use the route
+ * handler so we don't need to manage CDP sessions ourselves.
+ *
+ * What this fixes vs the v0.3.0 side-channel (`bt.fetchWithTls`):
+ *   - The side-channel only handled gating requests the caller made
+ *     explicitly. Page subresources, XHR, fetch() from page JS, all
+ *     went through Chrome's own TLS — meaning the host OS's Chrome
+ *     fingerprint reached the wire. With this rewriter installed, every
+ *     subresource also goes through Go.
+ *   - Cross-platform UA spoofing is restored. The daemon controls every
+ *     header on the wire; spoof to your heart's content.
+ *
+ * Known limitations:
+ *   - WebSocket upgrades can't be intercepted by Fetch.enable. They
+ *     bypass the rewriter and present Chrome's native TLS. The rewriter
+ *     logs WS leaks for awareness.
+ *   - Streaming responses are buffered fully. Bad for video, fine for
+ *     HTML/JSON/typical web pages.
+ *   - HTTP/3 (QUIC) requests bypass Fetch.enable entirely because Chrome
+ *     short-circuits them. We launch with `--disable-quic` so this never
+ *     fires in practice.
+ */
+import type { BrowserContext } from 'patchright';
+import type { TlsSideChannel } from './tls-side-channel.js';
+import type { Logger } from './logging.js';
+export interface TlsRewriterOptions {
+    /** TLS daemon spawned by `TlsSideChannel.spawn()`. The rewriter does
+     *  not own its lifecycle — caller is responsible for `close()`. */
+    channel: TlsSideChannel;
+    logger: Logger;
+    /** Hard timeout per request to the daemon. Default 30s. */
+    perRequestTimeoutMs?: number;
+    /** Profile name passed to the daemon for every request. Defaults to
+     *  `chrome_133`. Cross-platform spoofing happens by overriding this
+     *  per-launch (e.g. `chrome_124`) plus the User-Agent header. */
+    profile?: string;
+}
+export interface TlsRewriterStats {
+    /** Total requests intercepted. */
+    intercepted: number;
+    /** Requests fulfilled successfully via the daemon. */
+    fulfilled: number;
+    /** Requests that fell through to `route.continue()` because of an
+     *  error in the daemon path (e.g. daemon crashed, upstream timeout). */
+    fellThrough: number;
+    /** WebSocket upgrade requests we saw but couldn't intercept. */
+    webSocketLeaks: number;
+    /** Average daemon round-trip in ms. */
+    avgDurationMs: number;
+}
+/**
+ * Install the TLS rewriter on a Playwright BrowserContext. After this
+ * call, every HTTP/HTTPS request the browser issues is intercepted and
+ * forwarded through the TLS daemon. Returns a `stats()` accessor and an
+ * `uninstall()` callback.
+ */
+export declare function installTlsRewriter(context: BrowserContext, options: TlsRewriterOptions): Promise<{
+    stats: () => TlsRewriterStats;
+    uninstall: () => Promise<void>;
+}>;
+//# sourceMappingURL=tls-rewriter.d.ts.map

package/dist/tls-rewriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls-rewriter.d.ts","sourceRoot":"","sources":["../src/tls-rewriter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAuC,MAAM,YAAY,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAmC3C,MAAM,WAAW,kBAAkB;IACjC;uEACmE;IACnE,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;qEAEiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB;4EACwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC;IACT,KAAK,EAAE,MAAM,gBAAgB,CAAC;IAC9B,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC,CAAC,CAqID"}

package/dist/tls-rewriter.js

@@ -0,0 +1,203 @@
+/**
+ * TLS rewriting via CDP Fetch interception.
+ *
+ * The v0.5.0 answer to "every wire request should present a real Chrome
+ * TLS fingerprint, not just the gating ones." Without a TCP-level MITM
+ * proxy (and the OS-specific cert installation hell that entails), we
+ * use Chrome DevTools Protocol's `Fetch.enable` to pause every HTTP
+ * request the browser issues, hand it to the Go `bogdanfinn/tls-client`
+ * daemon for upstream execution, and fulfill the response back through
+ * CDP. The browser never opens an upstream TCP connection — all its
+ * HTTP is fulfilled by us.
+ *
+ * Patchright/Playwright expose this as `context.route('**', handler)`,
+ * which is the high-level wrapper around CDP Fetch. We use the route
+ * handler so we don't need to manage CDP sessions ourselves.
+ *
+ * What this fixes vs the v0.3.0 side-channel (`bt.fetchWithTls`):
+ *   - The side-channel only handled gating requests the caller made
+ *     explicitly. Page subresources, XHR, fetch() from page JS, all
+ *     went through Chrome's own TLS — meaning the host OS's Chrome
+ *     fingerprint reached the wire. With this rewriter installed, every
+ *     subresource also goes through Go.
+ *   - Cross-platform UA spoofing is restored. The daemon controls every
+ *     header on the wire; spoof to your heart's content.
+ *
+ * Known limitations:
+ *   - WebSocket upgrades can't be intercepted by Fetch.enable. They
+ *     bypass the rewriter and present Chrome's native TLS. The rewriter
+ *     logs WS leaks for awareness.
+ *   - Streaming responses are buffered fully. Bad for video, fine for
+ *     HTML/JSON/typical web pages.
+ *   - HTTP/3 (QUIC) requests bypass Fetch.enable entirely because Chrome
+ *     short-circuits them. We launch with `--disable-quic` so this never
+ *     fires in practice.
+ */
+/**
+ * Headers that Chrome's request lifecycle manages itself and that we
+ * MUST NOT pass through verbatim — re-sending them through the daemon
+ * either breaks the request (Content-Length) or duplicates state
+ * (Cookie, which the daemon will set automatically from the upstream's
+ * Set-Cookie response, while the browser's own cookie jar handles the
+ * reverse direction). The browser cookie jar IS the source of truth;
+ * we forward Cookie verbatim and let Set-Cookie come back via fulfill.
+ */
+const STRIP_REQUEST_HEADERS = new Set([
+    'host',
+    'content-length',
+    'connection',
+    'keep-alive',
+    'transfer-encoding',
+    'proxy-authorization',
+    'proxy-connection',
+    'upgrade',
+    'expect',
+]);
+/**
+ * Headers Chrome's response lifecycle re-computes and that we should
+ * NOT pass back via fulfill — letting them through breaks framing.
+ */
+const STRIP_RESPONSE_HEADERS = new Set([
+    'content-length',
+    'content-encoding', // upstream returns gzip; we hand fulfill the decoded body
+    'transfer-encoding',
+    'connection',
+    'keep-alive',
+]);
+/**
+ * Install the TLS rewriter on a Playwright BrowserContext. After this
+ * call, every HTTP/HTTPS request the browser issues is intercepted and
+ * forwarded through the TLS daemon. Returns a `stats()` accessor and an
+ * `uninstall()` callback.
+ */
+export async function installTlsRewriter(context, options) {
+    const { channel, logger } = options;
+    const profile = options.profile ?? 'chrome_133';
+    const perRequestTimeoutMs = options.perRequestTimeoutMs ?? 30_000;
+    let intercepted = 0;
+    let fulfilled = 0;
+    let fellThrough = 0;
+    let webSocketLeaks = 0;
+    let totalDurationMs = 0;
+    const handler = async (route, request) => {
+        intercepted++;
+        const url = request.url();
+        const method = request.method();
+        // WebSocket upgrades come through `route` but Fetch can't intercept
+        // the upgrade itself — Chrome handles WS frames at a layer we can't
+        // see from here. Let them pass through and log a warning.
+        if (request.isNavigationRequest() && (url.startsWith('ws://') || url.startsWith('wss://'))) {
+            webSocketLeaks++;
+            logger.warn('TLS rewriter: WebSocket leak — upgrade bypasses the rewriter', { url });
+            await route.continue();
+            return;
+        }
+        const upgradeHeader = request.headers()['upgrade'];
+        if (upgradeHeader && upgradeHeader.toLowerCase() === 'websocket') {
+            webSocketLeaks++;
+            logger.warn('TLS rewriter: WebSocket leak — upgrade bypasses the rewriter', { url });
+            await route.continue();
+            return;
+        }
+        // Build the daemon request from the browser-side request.
+        const reqHeaders = {};
+        for (const [key, value] of Object.entries(request.headers())) {
+            if (STRIP_REQUEST_HEADERS.has(key.toLowerCase()))
+                continue;
+            reqHeaders[key] = value;
+        }
+        const postBuffer = request.postDataBuffer();
+        const body = postBuffer ?? undefined;
+        try {
+            const resp = await Promise.race([
+                channel.fetch({
+                    url,
+                    method,
+                    headers: reqHeaders,
+                    body,
+                    profile,
+                    timeoutMs: perRequestTimeoutMs,
+                }),
+                new Promise((_resolve, reject) => {
+                    setTimeout(() => reject(new Error(`TLS rewriter: per-request timeout ${perRequestTimeoutMs}ms`)), perRequestTimeoutMs + 1000).unref();
+                }),
+            ]);
+            totalDurationMs += resp.durationMs;
+            // Flatten response headers. Multi-valued headers (e.g. Set-Cookie)
+            // need special handling: Playwright's fulfill takes a single string
+            // per key, but lets you pass an array via the headers parameter
+            // since 1.50 — we use the comma-join fallback for older versions.
+            // For Set-Cookie specifically, we use the multi-value extension
+            // because cookies must not be merged.
+            const respHeaders = {};
+            for (const [key, values] of Object.entries(resp.headers)) {
+                if (STRIP_RESPONSE_HEADERS.has(key.toLowerCase()))
+                    continue;
+                if (values.length === 1) {
+                    respHeaders[key] = values[0];
+                }
+                else {
+                    // For Set-Cookie, joining with comma is wrong (cookies have
+                    // their own commas in Expires). Playwright's `fulfill` accepts
+                    // multiValueHeaders via the headers field as Record<string, string>
+                    // by joining with `\n` for some headers. Safest fallback: pass
+                    // each Set-Cookie as a separate header by using the array form
+                    // if available, otherwise the last cookie wins.
+                    //
+                    // Since we can't pass arrays directly to Playwright's fulfill
+                    // headers, we encode the multi-value as `\n`-separated for
+                    // Set-Cookie (Chrome accepts this) and comma-join for everything
+                    // else.
+                    if (key.toLowerCase() === 'set-cookie') {
+                        respHeaders[key] = values.join('\n');
+                    }
+                    else {
+                        respHeaders[key] = values.join(', ');
+                    }
+                }
+            }
+            await route.fulfill({
+                status: resp.status,
+                headers: respHeaders,
+                body: resp.bodyBuffer,
+            });
+            fulfilled++;
+        }
+        catch (err) {
+            fellThrough++;
+            logger.warn('TLS rewriter: daemon path failed, falling through to native fetch', {
+                url,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            // Fall through to the browser's native request. Less stealthy but
+            // doesn't break the page.
+            try {
+                await route.continue();
+            }
+            catch {
+                // Route may already be fulfilled/aborted in race conditions; ignore.
+            }
+        }
+    };
+    // Install the route handler for all URLs. Patchright/Playwright accept
+    // a glob ('**/*') or RegExp; we use the glob for clarity.
+    await context.route('**/*', handler);
+    return {
+        stats: () => ({
+            intercepted,
+            fulfilled,
+            fellThrough,
+            webSocketLeaks,
+            avgDurationMs: fulfilled > 0 ? Math.round(totalDurationMs / fulfilled) : 0,
+        }),
+        uninstall: async () => {
+            try {
+                await context.unroute('**/*', handler);
+            }
+            catch {
+                // Context may be closing; ignore.
+            }
+        },
+    };
+}
+//# sourceMappingURL=tls-rewriter.js.map

package/dist/tls-rewriter.js.map

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

package/dist/tls-side-channel.d.ts

@@ -0,0 +1,91 @@
+/**
+ * TLS side-channel — spawns the Go-based bogdanfinn/tls-client daemon
+ * and exposes a `fetchWithTls()` primitive that performs HTTP requests
+ * with a real Chrome TLS ClientHello, real H2 frame settings, and real
+ * H2 frame order. Used to make gating requests that the browser can't
+ * make through itself, then inject the resulting cookies into the
+ * BlackTip browser session.
+ *
+ * This is the v0.3.0 answer to "an edge gates the very first request
+ * before BlackTip's browser even has a session." Use it as follows:
+ *
+ *   const channel = await TlsSideChannel.spawn();
+ *   const resp = await channel.fetch('https://protected.example.com/');
+ *   await bt.setCookies(resp.cookies.map(c => ({ name: c.name, value: c.value, domain: c.domain, path: c.path })));
+ *   await bt.navigate('https://protected.example.com/');
+ *   // ... browser session now has the cookies the gating request earned
+ *   await channel.close();
+ *
+ * The daemon binary lives in `native/tls-client/blacktip-tls` (Linux/macOS)
+ * or `native/tls-client/blacktip-tls.exe` (Windows). Build it once with
+ * `cd native/tls-client && go build -o blacktip-tls .` — Go is the only
+ * build dependency, and you can grab it from https://go.dev/dl/.
+ *
+ * The daemon stays alive across many requests so we don't pay subprocess
+ * startup cost per call. It uses a newline-delimited JSON wire protocol
+ * with per-request IDs, so multiple `fetch()` calls can be in flight
+ * concurrently without interleaving issues.
+ */
+export interface TlsRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    /** Request body as a UTF-8 string OR raw Buffer. Buffer is required for
+     *  binary uploads (multipart, octet-stream); string is fine for form
+     *  bodies and JSON. Encoded as base64 on the wire. */
+    body?: string | Buffer;
+    timeoutMs?: number;
+    /** Chrome / Firefox / Safari profile name; defaults to chrome_133. */
+    profile?: string;
+}
+export interface TlsResponse {
+    status: number;
+    /** Headers from the upstream response. Multi-valued — Set-Cookie commonly
+     *  has multiple entries. Header keys preserve the casing the upstream sent. */
+    headers: Record<string, string[]>;
+    /** Response body as a UTF-8 string. May be garbage for binary content;
+     *  use `bodyBuffer` for that. Kept as the primary body field for callers
+     *  that just want JSON / HTML. */
+    body: string;
+    /** Response body as raw bytes. Use this when the upstream returns binary
+     *  data (images, fonts, video, anything non-UTF-8). The TLS rewriting
+     *  route handler always uses this so subresources don't get mangled. */
+    bodyBuffer: Buffer;
+    finalUrl: string;
+    durationMs: number;
+    /** Cookies parsed from `Set-Cookie` headers, ready to inject via `bt.setCookies()`. */
+    cookies: ParsedCookie[];
+}
+export interface ParsedCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+}
+export declare class TlsSideChannel {
+    private proc;
+    private rl;
+    private pending;
+    private nextId;
+    private closed;
+    private constructor();
+    /**
+     * Spawn the daemon. Throws if the binary isn't built or can't start.
+     * The daemon stays alive until you call `close()`.
+     */
+    static spawn(): Promise<TlsSideChannel>;
+    private handleLine;
+    /**
+     * Perform a single TLS-impersonated request. Multiple `fetch()` calls
+     * can be in flight concurrently — the daemon handles each in its own
+     * goroutine and matches responses by id.
+     */
+    fetch(req: TlsRequest): Promise<TlsResponse>;
+    /** Shut down the daemon and clean up the subprocess. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=tls-side-channel.d.ts.map

package/dist/tls-side-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls-side-channel.d.ts","sourceRoot":"","sources":["../src/tls-side-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAUH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;0DAEsD;IACtD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf;mFAC+E;IAC/E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC;;sCAEkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb;;4EAEwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAoGD,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAiC;IAC7C,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO;IAYP;;;OAGG;WACU,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAU7C,OAAO,CAAC,UAAU;IAgDlB;;;;OAIG;IACG,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IA4BlD,wDAAwD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAc7B"}