@rester159/blacktip 0.1.0 → 0.4.0

package/docs/anti-bot-validation.md

@@ -0,0 +1,84 @@
+# Anti-bot validation scoreboard
+
+This document records BlackTip's results against commercial anti-bot vendors on real, in-the-wild targets. Every entry is generated by `bt.testAgainstAntiBot(url)`, which both detects challenge/block pages AND captures vendor signals (cookies, scripts) on a passing page so we can prove the target is actually protected — not a false negative on an unprotected URL.
+
+Methodology and reproduction recipe at the bottom.
+
+## Live scoreboard — 2026-04-09 (BlackTip 0.2.0)
+
+| Target | Vendors detected on page | Block? | Vendor signals on success | Notes |
+|---|---|---|---|---|
+| **vinted.com** | DataDome | pass | datadome cookie, cloudflare script | Real catalog renders with prices, brands, listings |
+| **bestbuy.com** | Akamai | pass | akamai cookie + script | Earlier classification as PerimeterX was wrong — BestBuy is Akamai |
+| **walmart.com** | Akamai + PerimeterX | pass | akamai cookie + script, perimeterx cookie + script | Walmart runs both vendors simultaneously; BlackTip slides past both |
+| **crunchbase.com** | Cloudflare | pass | cloudflare script | Real homepage content visible |
+| **ticketmaster.com** | none detected on homepage | pass | none on `/` | TM only arms PerimeterX on event/checkout pages, not the marketing homepage |
+| **opentable.com** (Gjelina deep link, restref=76651) | Akamai | pass | akamai cookie + script | Real time slots render; Reservation at Gjelina, Apr 11 2026 |
+| **chatgpt.com** | Cloudflare | pass | cloudflare script + cf_clearance cookie | **Cloudflare managed challenge auto-passed**; cf_clearance issued silently |
+| **twitch.tv** | Kasada | pass | kasada script signal | **Kasada validated** — first published BlackTip pass against a real Kasada-armed target |
+| **canadagoose.com** | (no live signals on homepage) | pass | none | Was historically Kasada but the homepage no longer surfaces Kasada cookies/scripts; may be lazy-loaded on cart/checkout |
+| **hyatt.com** | (no live signals on landing page) | pass | none on `/loyalty/en-US` | RT (Akamai mPulse RUM) present, no Bot Manager indicators |
+| **footlocker.com** | (no live signals on homepage) | pass | none | Same as Canada Goose — Kasada may arm only on PDP/cart |
+| **datadome.co/bot-tester** | DataDome (bypassed via marketing redirect) | pass | none captured | Redirected to /signup/ with marketing content; DataDome did not arm a challenge |
+| **antoinevastel.com/bots-vue.html** | none | pass | none | Demo page no longer arms a probe — author moved to a marketing homepage |
+| **nowsecure.nl** (Cloudflare bot fight, nodriver author's benchmark) | none | pass | none on this barebones page | Passes regression — earlier validation in v0.1.0 |
+
+### Cloudflare managed challenge — silent auto-pass evidence
+
+The `cf_clearance` cookie is set ONLY after Cloudflare's managed challenge accepts a request as human. Across the v0.3.0 validation run, BlackTip earned `cf_clearance` cookies on multiple Cloudflare-protected domains without ever surfacing a "Just a moment..." interstitial to the user:
+
+- `.vinted.com` (cf_clearance httpOnly)
+- `.crunchbase.com` (cf_clearance httpOnly)
+- `.chatgpt.com` (cf_clearance httpOnly + cf_bm + cfuvid)
+
+These cookies are not visible to `document.cookie` because they are httpOnly — the v0.2.0 detector missed them. v0.3.0 fixed the detector to read via the BlackTip cookies API, surfacing this evidence. **A `cf_clearance` cookie is the strongest possible proof of a Cloudflare managed-challenge pass on a real Chrome session.**
+
+**Eight commercial-detector targets, eight passes.** The most load-bearing validations are Walmart (Akamai + PerimeterX simultaneously) and OpenTable (Akamai's full Bot Manager on a high-value booking endpoint that previously hard-blocked v0.1.0).
+
+## What "passing" means here
+
+`bt.testAgainstAntiBot(url)` returns `passed: true` when:
+1. The page title does not match a known vendor block pattern (Akamai "Access Denied", Cloudflare "Just a moment...", PerimeterX "Press & Hold", DataDome captcha-delivery interstitial, Imperva incident page, etc.)
+2. The body text does not contain vendor block markers
+3. Real page content is rendered (verifiable in `bodyPreview`)
+
+The `vendorSignals` field separately reports what vendor cookies and scripts are present even on a passing page. If a target shows `vendorSignals: []`, either the vendor doesn't arm protection on that URL (Ticketmaster homepage), or BlackTip's signal patterns missed something — note both honestly here.
+
+## Vendors recognised
+
+| Vendor | Block-page tells | Cookie tells | Script tells |
+|---|---|---|---|
+| Akamai Bot Manager | title `Access Denied`, body `errors.edgesuite.net`, `Reference #...` | `_abck`, `bm_sz`, `ak_bmsc`, `bm_sv` | `akam/`, `ak.bmpsdk`, `akamaihd.net/sensor` |
+| DataDome | body `geo.captcha-delivery.com`, `datado.me` | `datadome`, `dd_s`, `dd_cookie_test_` | `js.datadome.co`, `datado.me` |
+| Cloudflare Bot Fight / Turnstile | title `Just a moment...`, body `cf-browser-verification`, `Sorry, you have been blocked` | `cf_clearance`, `__cf_bm`, `__cflb` | `challenges.cloudflare.com`, `cdn-cgi/challenge-platform` |
+| HUMAN / PerimeterX | title `Access to this page has been denied`, body `Press & Hold` | `_px*`, `_pxhd` | `perimeterx`, `px-cdn`, `px-captcha`, `human-security` |
+| Imperva / Incapsula | body `Request unsuccessful. Incapsula incident ID` | `visid_incap_`, `incap_ses_` | (mostly server-side) |
+| Kasada | body `kpsdk` | (none captured) | `x-kpsdk-` headers, `ips.js` |
+| Arkose Labs / FunCaptcha | body `client-api.arkoselabs.com`, `funcaptcha` | (none captured) | `client-api.arkoselabs.com` |
+
+## How to reproduce
+
+```bash
+# Terminal 1
+cd /path/to/blacktip
+node dist/cli.js serve
+
+# Terminal 2 — single target
+node dist/cli.js send "return await bt.testAgainstAntiBot('https://www.vinted.com/')" --pretty
+
+# Or batch:
+node dist/cli.js batch '[
+  "return await bt.testAgainstAntiBot(\"https://www.vinted.com/\")",
+  "return await bt.testAgainstAntiBot(\"https://www.bestbuy.com/\")",
+  "return await bt.testAgainstAntiBot(\"https://www.walmart.com/\")",
+  "return await bt.testAgainstAntiBot(\"https://www.crunchbase.com/\")",
+  "return await bt.testAgainstAntiBot(\"https://www.opentable.com/booking/restref/availability?rid=76651&restref=76651&partySize=2&dateTime=2026-04-11T19%3A00\")"
+]'
+```
+
+## Caveats
+
+- **One-shot probes.** This scoreboard records single navigations from a residential IP. Anti-bot vendors profile sessions over time and across requests; a target that passes a one-shot probe may still flag a multi-step automation flow where the behavioral signature looks too clean. The deep validation is the OpenTable booking flow itself, where we drove the form to completion through Akamai's Bot Manager.
+- **Vendor classification can be wrong.** Targets like Walmart run multiple vendors in parallel. The `vendorSignals` field is the source of truth; the "expected vendor" column above is informational.
+- **IP matters.** Run from a residential network or known-clean residential proxy. A datacenter IP will fail every entry on this scoreboard regardless of how good BlackTip's stealth is. Use `bt.checkIpReputation()` first.
+- **The scoreboard goes stale.** Vendors update their detection logic constantly. Re-run on each release and update this doc. If a target moves from pass to fail, file it against the next BlackTip version, capture the failing fingerprint, and dig in.

package/docs/calibration-validation.md

@@ -0,0 +1,93 @@
+# Behavioral calibration validation (v0.3.0)
+
+This document records the result of fitting BlackTip's behavioral profile against the real CMU Keystroke Dynamics dataset (Killourhy & Maxion 2009) and validating the fit against held-out subjects.
+
+## TL;DR
+
+The calibrated profile measurably beats BlackTip's canonical `HUMAN_PROFILE` on a held-out subject set:
+
+| Metric | Canonical KS distance | Calibrated KS distance | Improvement |
+|---|---|---|---|
+| **Hold time** | 0.4297 | 0.2018 | **53% closer to real humans** |
+| **Flight time** | 0.4811 | 0.4152 | 13.7% closer to real humans |
+
+This is the first time the BlackTip behavioral pipeline has been validated end-to-end against a real public dataset. Up through v0.2.0, the engine's parameters were sane defaults; v0.3.0 makes them empirically grounded.
+
+## Methodology
+
+1. **Dataset**: CMU Keystroke Dynamics (`DSL-StrongPasswordData.csv`) — 51 subjects each typing the fixed phrase `.tie5Roanl` 50 times across 8 sessions, for 20,400 total phrase reps.
+2. **Split**: deterministic 80/20 by subject. 40 subjects (16,000 phrases) → training. 11 subjects (4,400 phrases) → held-out test.
+3. **Fit**: training set → `fitTypingDynamics()` → empirical hold-time and flight-time distributions plus per-digraph latencies.
+4. **Compare**: synthesized 5,000 samples from each of (a) BlackTip's canonical `HUMAN_PROFILE` ranges and (b) the fitted `[p5, p95]` ranges. Computed Kolmogorov–Smirnov distance (max empirical CDF gap) against the held-out test set.
+5. **Report**: lower KS distance → closer to real human distribution.
+
+The KS test is the standard non-parametric goodness-of-fit measure. It does not assume any particular distribution shape, which matters here because keystroke timings are right-skewed log-normal-ish, not Gaussian. The improvement ratio is `1 - calibrated / canonical`.
+
+## Fitted parameters
+
+```
+Hold time:
+  mean = 90.3 ms
+  p5   = 48.3 ms
+  p50  = 85.8 ms
+  p95  = 148.8 ms
+
+Flight time:
+  mean = 151.4 ms
+  p5   = 0.0   ms   (some adjacent keystrokes overlap — concurrent press/release)
+  p50  = 91.3  ms
+  p95  = 513.5 ms
+
+Digraphs fit: 6 (the unique a–z transitions in the phrase)
+```
+
+The fitted profile is saved to `data/cmu-keystroke/calibrated-profile.json` and ready to load:
+
+```typescript
+import calibrated from './data/cmu-keystroke/calibrated-profile.json' with { type: 'json' };
+import { BlackTip } from '@rester159/blacktip';
+
+const bt = new BlackTip({
+  behaviorProfile: calibrated.profileConfig,
+  // ... rest of your config
+});
+```
+
+## Why this matters
+
+Behavioral biometrics services (BioCatch, NuData, SecuredTouch) profile users on dimensions like:
+
+- Hold time mean and variance per key
+- Flight time distributions per digraph
+- Tap pressure (mobile only — n/a here)
+- Mouse curvature, click dwell, scroll deceleration
+
+A bot that types with uniform 100 ms holds and flat flight times stands out instantly because real humans have right-skewed log-normal distributions with subject-specific clustering. BlackTip's canonical `HUMAN_PROFILE` was already in the right ballpark, but the canonical hold-time range `[50, 200]` was 53% farther from the real distribution than the empirically-fitted `[48, 149]`. The fitted range is tighter and centered correctly, so BlackTip's keystroke output now sits inside the real human distribution rather than scattered across a too-wide canonical range.
+
+## Reproducing the result
+
+```bash
+cd /path/to/blacktip
+mkdir -p data/cmu-keystroke
+curl -fsSL -o data/cmu-keystroke/DSL-StrongPasswordData.csv \
+  https://www.cs.cmu.edu/~keystroke/DSL-StrongPasswordData.csv
+npm run build
+node scripts/fit-cmu-keystroke.mjs
+```
+
+The script writes its output to `data/cmu-keystroke/calibrated-profile.json` and prints the validation table to stdout. Re-runs are deterministic (the train/test split is sorted, not random) so the numbers match this document byte-for-byte.
+
+## What this does NOT prove
+
+- The KS test compares marginal distributions, not joint ones. A profile that matches the marginals perfectly could still have unrealistic correlation structure (e.g. correct hold times but uncorrelated with flight times). A real biometrics test against a commercial service would catch this; we don't have one.
+- The CMU dataset is 50 reps of one fixed phrase from each of 51 American English typists. The fitted profile generalises best to American English long-form typing; non-Latin scripts and very short fields may need a different calibration.
+- Flight time fit improvement (13.7%) is much smaller than hold time (53%). The CMU phrase is short and contains transitions that aren't representative of free-text typing — the held-out flights span a wide range that the canonical `[80, 150]` and fitted `[0, 514]` are both bad fits for. A larger free-text dataset (e.g. Buffalo or GREYC) would likely produce a better flight fit. Future work.
+
+## Future calibration sources
+
+Once a parser exists for each, the same pipeline applies:
+
+- **Balabit Mouse Dynamics Challenge** — for `fitMouseDynamics()`. Parser exists in `parseBalabitMouseCsv()`; needs an actual fit run against the real dataset.
+- **GREYC-NISLAB** — free-text keystroke dynamics from 110 subjects. Better representative coverage than CMU's fixed phrase.
+- **Buffalo Free-Text** — multi-session keystroke data across 148 subjects. The canonical reference for keystroke behavioral biometrics literature.
+- Your own telemetry — `parseGenericTelemetryJson()` accepts the normalized `MouseMovement` / `TypingSession` shapes directly. Bring your own data.

package/docs/identity-pool.md

@@ -0,0 +1,176 @@
+# IdentityPool — long-running session and identity rotation (v0.4.0)
+
+`IdentityPool` is BlackTip's answer to the question "how do I rotate across many identities cleanly without my whole flow looking like one bot retried under different IPs?" An identity is the union of everything that makes a session look like one specific human: cookies, localStorage, proxy, device profile, behavior profile, locale, timezone. The pool persists to a JSON file so identities survive restarts, and each identity has a per-domain burn list so an identity blocked on opentable.com is still eligible for amazon.com.
+
+## When you need this
+
+Most BlackTip flows do not need an IdentityPool. A single launch with the right device profile and a residential connection covers the common case. The pool earns its keep when:
+
+1. You're running many flows against the same target and need to look like many different users (price scraping, market research, multi-account ops on services where multi-account is allowed).
+2. You want resilience: when identity A gets blocked on opentable.com, you want identity B to take over without manual intervention.
+3. You want session persistence across process restarts so a logged-in identity from yesterday is still logged in today.
+4. You want a feedback loop: when an identity gets burned, the proxy bound to it should be marked dirty in `ProxyPool` so it isn't reused for the same target until the ban window decays.
+
+## Composition
+
+`IdentityPool` does not reinvent persistence or proxy selection. It composes:
+
+- **`SnapshotManager`** for cookies + localStorage + sessionStorage. The pool calls `captureSnapshot(bt, identity)` after a successful flow to save state.
+- **`ProxyPool`** for proxy selection and ban tracking. New identities draw a proxy from the pool at creation time. When an identity is burned per-domain, the pool reports a ban on that proxy/domain pair so future selections skip it.
+- **`BlackTipConfig`** is produced by `pool.applyToConfig(identity)` and passed to `new BlackTip(config)`.
+
+## Quick start
+
+```typescript
+import { BlackTip, IdentityPool, ProxyPool, ProxyProviders } from '@rester159/blacktip';
+
+// 1. Build a ProxyPool from whatever provider you use.
+const proxyPool = new ProxyPool([
+  ProxyProviders.brightData('your-customer-id', 'your-password', 'residential'),
+  ProxyProviders.oxylabs('your-username', 'your-password'),
+]);
+
+// 2. Build the IdentityPool, backed by a JSON file on disk.
+const pool = new IdentityPool({
+  storePath: './.blacktip/identities.json',
+  proxyPool,
+  rotationPolicy: {
+    maxUses: 50,            // burn after 50 uses
+    maxAgeMs: 7 * 24 * 60 * 60 * 1000, // burn after 7 days idle
+  },
+});
+
+// 3. First time only: seed the pool with N identities. Subsequent runs
+// load from the store file.
+if (pool.size() === 0) {
+  for (let i = 0; i < 5; i++) {
+    pool.add({
+      deviceProfile: i % 2 === 0 ? 'desktop-windows' : 'desktop-macos',
+      label: `identity-${i + 1}`,
+      locale: 'en-US',
+      timezone: 'America/New_York',
+    });
+  }
+}
+
+// 4. For each flow: acquire, launch, run, capture, release.
+const identity = pool.acquire('opentable.com');
+if (!identity) throw new Error('No eligible identity for opentable.com — pool exhausted');
+
+const config = pool.applyToConfig(identity, { logLevel: 'info', timeout: 15_000 });
+const bt = new BlackTip(config);
+await bt.launch();
+
+// Restore the identity's prior session (cookies, storage). No-op if first use.
+await pool.restoreSnapshot(bt, identity);
+
+try {
+  await bt.navigate('https://www.opentable.com/');
+  await bt.waitForStable();
+  // ... rest of the flow
+
+  // On success, save the updated session state back into the identity.
+  await pool.captureSnapshot(bt, identity);
+} catch (err) {
+  // On failure, mark this identity burned for this domain. The proxy
+  // gets banned in ProxyPool too, so the next identity drawn from the
+  // pool won't reuse the same proxy on this target.
+  pool.markBurned(identity.id, err instanceof Error ? err.message : String(err), 'opentable.com');
+} finally {
+  await bt.close();
+}
+```
+
+## API
+
+### `new IdentityPool(options)`
+
+```typescript
+{
+  storePath: string;              // required — JSON file path
+  proxyPool?: ProxyPool;          // optional — for proxy binding & feedback
+  rotationPolicy?: {
+    maxUses?: number;             // default: Infinity
+    maxAgeMs?: number;            // default: Infinity
+    preferLeastRecentlyUsed?: boolean; // default: true
+  };
+}
+```
+
+### `add(init)` → `Identity`
+
+Create a new identity. `deviceProfile` is required. If a `proxyPool` was supplied to the IdentityPool and `proxy` is omitted, the pool draws one. Auto-saves to disk.
+
+### `acquire(domain?)` → `Identity | null`
+
+Pick an identity for use. Skips identities burned on the requested domain. Applies rotation policy: identities exceeding `maxUses` or `maxAgeMs` are auto-burned. Returns null if no eligible identity exists.
+
+### `markBurned(id, reason, domain?)` → `boolean`
+
+Mark an identity burned. With `domain`, only burns for that domain (per-domain burn list). Without `domain`, fully burns the identity. Per-domain burns also report a proxy ban back to `ProxyPool` if one is wired up.
+
+### `clearBurn(id, domain?)` → `boolean`
+
+Manually unban. Useful when you know the burn was a transient issue.
+
+### `applyToConfig(identity, baseConfig?)` → `BlackTipConfig`
+
+Build a `BlackTipConfig` from an identity. Sets `deviceProfile`, `behaviorProfile`, `locale`, `timezone`, and `proxy` (URL-formatted via `proxyToUrl`). Other base config fields pass through unchanged.
+
+### `restoreSnapshot(bt, identity)` → `Promise<void>`
+
+After `bt.launch()`, apply the identity's saved cookies + localStorage to the running browser. No-op if the identity has no snapshot yet.
+
+### `captureSnapshot(bt, identity)` → `Promise<void>`
+
+Save the current BlackTip session state into the identity. Call after a successful flow so the next acquire of this identity starts from a known-good logged-in state.
+
+### `list()`, `available()`, `size()`, `remove(id)`
+
+Standard inspection. `available()` returns identities not fully burned (per-domain burns don't count).
+
+## Persistence format
+
+The store file is plain JSON with a schema version. Sample:
+
+```json
+{
+  "version": 1,
+  "savedAt": "2026-04-10T22:30:00.000Z",
+  "identities": [
+    {
+      "id": "1f2e3d4c-...",
+      "label": "identity-1",
+      "createdAt": "2026-04-10T20:00:00.000Z",
+      "lastUsedAt": "2026-04-10T22:25:00.000Z",
+      "useCount": 12,
+      "burnedAt": null,
+      "burnedReason": null,
+      "burnedDomains": ["sears.com"],
+      "snapshot": { /* SessionSnapshot */ },
+      "proxy": { "id": "brightdata-residential", "...": "..." },
+      "behaviorProfile": "human",
+      "deviceProfile": "desktop-windows",
+      "locale": "en-US",
+      "timezone": "America/New_York"
+    }
+  ]
+}
+```
+
+The schema is versioned so future migrations are explicit. Don't hand-edit the file while a process is reading it — use the API.
+
+## IP reputation gate
+
+v0.4.0 also adds `BlackTipConfig.requireResidentialIp`. When set, BlackTip runs `bt.checkIpReputation()` immediately after `launch()` and either warns or throws based on the verdict:
+
+```typescript
+new BlackTip({
+  // 'throw': refuse to launch if egress IP is on a known datacenter ASN.
+  // 'warn':  log a warning but allow the launch.
+  // false / unset: no check.
+  requireResidentialIp: 'throw',
+});
+```
+
+Use `'throw'` in production / CI where a flagged IP would burn a real account. Use `'warn'` for local dev. Combine with `IdentityPool` and `ProxyPool` to ensure every launch goes through a residential exit before touching the target.

package/docs/tls-side-channel.md

@@ -0,0 +1,83 @@
+# TLS side-channel (v0.3.0)
+
+The v0.3.0 answer to "an edge gates the very first request before BlackTip's browser even has a session." BlackTip ships a Go-based daemon built on `bogdanfinn/tls-client` that performs HTTP requests with a real Chrome TLS ClientHello, real H2 frame settings, and real H2 frame order. You use it to make gating requests the browser can't make through itself, then inject the resulting cookies into the browser session before navigating.
+
+## When you need this
+
+Most BlackTip flows do not need the TLS side-channel. The browser's own TLS via `channel: 'chrome'` is real Chrome and passes every detector we've validated against. The side-channel is for the cases where it isn't enough:
+
+1. **First-request edge gating.** Some Akamai-protected sites refuse to serve a session cookie to a navigation that doesn't already have one. You hit them via the side-channel first (which goes through `bm_s` → sensor data POST → `bm_sv` issuance), then inject the resulting cookies into the browser and navigate normally.
+2. **Cross-platform User-Agent spoofing.** You're running on Linux but want the target to see Windows. The browser's TLS comes from the host OS Chrome, so you can't fake the platform without a TLS rewriter. The side-channel can. v0.2.0's L016 fix removed the broken UA-override path; this is the supported alternative.
+3. **API-level operations.** You want to call a JSON API the site exposes, but the API edge enforces the same TLS profile as the browser. Use the side-channel to call the API without paying browser-render overhead per request.
+4. **Pre-warming for proxy rotation.** You're rotating residential proxies and need to "warm" each new IP with a Chrome-TLS handshake before the browser session uses it.
+
+## Build the daemon
+
+The daemon is a small Go program in `native/tls-client/`. Go is the only build dependency. Install Go from https://go.dev/dl/ then:
+
+```bash
+cd native/tls-client
+go build -o blacktip-tls .       # Linux / macOS
+go build -o blacktip-tls.exe .   # Windows
+```
+
+The build produces a single ~14 MB statically-linked binary. BlackTip resolves it via `native/tls-client/blacktip-tls[.exe]` automatically; override with `BLACKTIP_TLS_BIN=/abs/path/to/binary` if you want to ship it elsewhere.
+
+## Usage
+
+```typescript
+import { BlackTip } from '@rester159/blacktip';
+
+const bt = new BlackTip({ logLevel: 'info' });
+await bt.launch();
+
+// 1. Make the gating request through the side-channel.
+const resp = await bt.fetchWithTls({
+  url: 'https://www.opentable.com/',
+  headers: {
+    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36',
+    'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
+    'Accept-Language': 'en-US,en;q=0.9',
+  },
+});
+console.log('TLS fetch status:', resp.status);
+console.log('Earned cookies:', resp.cookies.map(c => c.name));
+
+// 2. Inject the cookies into the browser session.
+const injected = await bt.injectTlsCookies(resp, 'https://www.opentable.com/');
+console.log('Injected', injected, 'cookies');
+
+// 3. Navigate normally — the browser carries the side-channel-earned tokens.
+await bt.navigate('https://www.opentable.com/');
+await bt.waitForStable();
+// ... rest of flow
+
+await bt.close();   // Closes the TLS daemon too
+```
+
+## Architecture
+
+- **Wire protocol**: newline-delimited JSON over the daemon's stdin/stdout. Each request has a string `id`; responses match by id, so multiple in-flight `fetch()` calls don't interleave.
+- **Daemon lifecycle**: spawned lazily on first `fetchWithTls()` call, kept alive until `bt.close()`. No subprocess startup cost per request.
+- **Concurrency**: the daemon handles each request in its own Go goroutine. The Node side dispatches them in parallel and reassembles by id.
+- **Profile selection**: defaults to `chrome_133`. Override per-request via `bt.fetchWithTls({ url, profile: 'chrome_124' })`. Available profiles are whatever `bogdanfinn/tls-client/profiles` ships — at the time of writing: `chrome_120`, `chrome_124`, `chrome_131`, `chrome_133`, `firefox_120`, `safari_ios_16_0`.
+- **Body encoding**: bodies are base64 on the wire to avoid newline / Unicode issues with the line-delimited protocol. The wrapper handles encoding/decoding transparently.
+
+## Validated TLS fingerprint
+
+Run via the integration test (`tests/tls-side-channel.integration.test.ts`):
+
+```
+JA4: t13d1516h2_8daaf6152771_d8a2da3f94cd
+First cipher: TLS_GREASE (0x5A5A)
+HTTP/2 Akamai fingerprint: 1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
+```
+
+This is byte-for-byte identical to real Chrome 133. The leading `t13d` JA4 prefix confirms TLS 1.3 with Chrome's count signature; the GREASE first cipher confirms proper GREASE rotation; the H2 fingerprint matches Chrome's frame settings and frame order (`m,a,s,p` = method/authority/scheme/path).
+
+## Caveats
+
+- **Not a Chrome browser.** The side-channel is HTTP-only — no JavaScript execution, no DOM, no Cookie JAR persistence beyond what you inject manually. You use it to acquire tokens, not to drive a flow.
+- **Akamai sensor data is not bypassed.** A first request to an Akamai-protected URL through the side-channel returns 403 with `bm_s`/`bm_ss`/`bm_so` set — the same place a browser would be at after one request. Akamai expects a sensor data POST to follow before serving 200s. The side-channel collects the session cookies; the sensor POST is not yet automated. You can either (a) inject the bm_s cookies into the browser and let the browser do the sensor POST (this is what the OpenTable validation flow does), or (b) implement the sensor POST yourself.
+- **Always set the User-Agent header.** The Go HTTP client defaults to `Go-http-client/2.0` if you don't override it. That's a textbook automation tell. The wrapper auto-sets `Accept-Language` to `en-US,en;q=0.9` if missing, but UA is your job.
+- **Linux/macOS support is built but not validated in CI.** The `go build` command produces native binaries for whatever platform you run it on; the Node-side `resolveBinaryPath()` picks the right name based on `process.platform`. If you ship to a server, build the daemon in the same OS the server runs.

package/native/tls-client/go.mod

@@ -0,0 +1,21 @@
+module github.com/rester159/blacktip/native/tls-client
+
+go 1.26.2
+
+require (
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/bdandy/go-errors v1.2.2 // indirect
+	github.com/bdandy/go-socks4 v1.2.3 // indirect
+	github.com/bogdanfinn/fhttp v0.6.8 // indirect
+	github.com/bogdanfinn/quic-go-utls v1.0.9-utls // indirect
+	github.com/bogdanfinn/tls-client v1.14.0 // indirect
+	github.com/bogdanfinn/utls v1.7.7-barnius // indirect
+	github.com/bogdanfinn/websocket v1.5.5-barnius // indirect
+	github.com/klauspost/compress v1.18.2 // indirect
+	github.com/quic-go/qpack v0.6.0 // indirect
+	github.com/tam7t/hpkp v0.0.0-20160821193359-2b70b4024ed5 // indirect
+	golang.org/x/crypto v0.46.0 // indirect
+	golang.org/x/net v0.48.0 // indirect
+	golang.org/x/sys v0.39.0 // indirect
+	golang.org/x/text v0.32.0 // indirect
+)

package/native/tls-client/go.sum

@@ -0,0 +1,36 @@
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/bdandy/go-errors v1.2.2 h1:WdFv/oukjTJCLa79UfkGmwX7ZxONAihKu4V0mLIs11Q=
+github.com/bdandy/go-errors v1.2.2/go.mod h1:NkYHl4Fey9oRRdbB1CoC6e84tuqQHiqrOcZpqFEkBxM=
+github.com/bdandy/go-socks4 v1.2.3 h1:Q6Y2heY1GRjCtHbmlKfnwrKVU/k81LS8mRGLRlmDlic=
+github.com/bdandy/go-socks4 v1.2.3/go.mod h1:98kiVFgpdogR8aIGLWLvjDVZ8XcKPsSI/ypGrO+bqHI=
+github.com/bogdanfinn/fhttp v0.6.8 h1:LiQyHOY3i0QoxxNB7nq27/nGNNbtPj0fuBPozhR7Ws4=
+github.com/bogdanfinn/fhttp v0.6.8/go.mod h1:A+EKDzMx2hb4IUbMx4TlkoHnaJEiLl8r/1Ss1Y+5e5M=
+github.com/bogdanfinn/quic-go-utls v1.0.9-utls h1:tV6eDEiRbRCcepALSzxR94JUVD3N3ACIiRLgyc2Ep8s=
+github.com/bogdanfinn/quic-go-utls v1.0.9-utls/go.mod h1:aHph9B9H9yPOt5xnhWKSOum27DJAqpiHzwX+gjvaXcg=
+github.com/bogdanfinn/tls-client v1.14.0 h1:vyk7Cn4BIvLAGVuMfb0tP22OqogfO1lYamquQNEZU1A=
+github.com/bogdanfinn/tls-client v1.14.0/go.mod h1:LsU6mXVn8MOFDwTkyRfI7V1BZM1p0wf2ZfZsICW/1fM=
+github.com/bogdanfinn/utls v1.7.7-barnius h1:OuJ497cc7F3yKNVHRsYPQdGggmk5x6+V5ZlrCR7fOLU=
+github.com/bogdanfinn/utls v1.7.7-barnius/go.mod h1:aAK1VZQlpKZClF1WEQeq6kyclbkPq4hz6xTbB5xSlmg=
+github.com/bogdanfinn/websocket v1.5.5-barnius h1:bY+qnxpai1qe7Jmjx+Sds/cmOSpuuLoR8x61rWltjOI=
+github.com/bogdanfinn/websocket v1.5.5-barnius/go.mod h1:gvvEw6pTKHb7yOiFvIfAFTStQWyrm25BMVCTj5wRSsI=
+github.com/klauspost/compress v1.18.2 h1:iiPHWW0YrcFgpBYhsA6D1+fqHssJscY/Tm/y2Uqnapk=
+github.com/klauspost/compress v1.18.2/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
+github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
+github.com/tam7t/hpkp v0.0.0-20160821193359-2b70b4024ed5 h1:YqAladjX7xpA6BM04leXMWAEjS0mTZ5kUU9KRBriQJc=
+github.com/tam7t/hpkp v0.0.0-20160821193359-2b70b4024ed5/go.mod h1:2JjD2zLQYH5HO74y5+aE3remJQvl6q4Sn6aWA2wD1Ng=
+golang.org/x/crypto v0.46.0 h1:cKRW/pmt1pKAfetfu+RCEvjvZkA9RimPbh7bhFjGVBU=
+golang.org/x/crypto v0.46.0/go.mod h1:Evb/oLKmMraqjZ2iQTwDwvCtJkczlDuTmdJXoZVzqU0=
+golang.org/x/net v0.0.0-20211104170005-ce137452f963/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
+golang.org/x/net v0.48.0 h1:zyQRTTrjc33Lhh0fBgT/H3oZq9WuvRR5gPC70xpDiQU=
+golang.org/x/net v0.48.0/go.mod h1:+ndRgGjkh8FGtu1w1FGbEC31if4VrNVMuKTgcAAnQRY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.39.0 h1:CvCKL8MeisomCi6qNZ+wbb0DN9E5AATixKsvNtMoMFk=
+golang.org/x/sys v0.39.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
+golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=