@rester159/blacktip 0.2.0 → 0.5.0

package/docs/tls-rewriting.md

@@ -0,0 +1,121 @@
+# Full TLS rewriting (v0.5.0)
+
+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, BlackTip uses 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. Every wire request presents real Chrome TLS via Go.**
+
+## What this gives you over the v0.3.0 side-channel
+
+The v0.3.0 `bt.fetchWithTls()` only handled gating requests the caller made explicitly. Page subresources, XHR, `fetch()` from page JS — all of those went through Chrome's own TLS, meaning the host OS's Chrome fingerprint reached the wire on every subresource. With the v0.5.0 rewriter installed, **every** subresource also goes through Go.
+
+What changes:
+- **Cross-platform UA spoofing is restored.** v0.2.0's L016 fix removed the broken context-level UA override because it caused User-Agent / Sec-Ch-Ua mismatch. With the rewriter, the daemon controls every header on the wire — spoof to your heart's content.
+- **JA4 / GREASE / H2 fingerprint of every request matches real Chrome 133** (or whatever profile you select), regardless of what Chrome the host OS has installed. Useful when you need to impersonate a specific Chrome version that doesn't ship for your platform.
+- **One source of truth for TLS.** No more "the gating request matched but the subresource didn't" inconsistency that anti-bot vendors can fingerprint at the session level.
+
+## Validated end-to-end
+
+Run `npx vitest run tests/tls-rewriter.integration.test.ts` (requires the Go daemon binary). The load-bearing assertion is:
+
+```
+JA4: t13d1516h2_8daaf6152771_d8a2da3f94cd       (textbook Chrome 133)
+First cipher: TLS_GREASE (0x3A3A)               (rotated each connection)
+HTTP/2 fingerprint: 1:65536;2:0;4:6291456;6:262144|15663105|0|m,a,s,p
+```
+
+This is the JA4 reaching tls.peet.ws **via the browser navigation** (not via a direct daemon call). The browser navigated to `tls.peet.ws/api/all`, the JSON it received back came from an upstream connection that the Go daemon opened, not Chrome.
+
+## Usage
+
+```typescript
+import { BlackTip } from '@rester159/blacktip';
+
+const bt = new BlackTip({
+  logLevel: 'info',
+  timeout: 30_000,
+  // The headline knob — when set to 'all', every request the browser
+  // issues is intercepted via CDP Fetch and forwarded through the Go
+  // daemon for upstream execution.
+  tlsRewriting: 'all',
+});
+
+await bt.launch();
+await bt.navigate('https://www.opentable.com/');
+
+// Verify the rewriter is doing what you expect
+console.log(bt.getTlsRewriterStats());
+// {
+//   intercepted: 47,
+//   fulfilled: 45,
+//   fellThrough: 0,
+//   webSocketLeaks: 0,
+//   avgDurationMs: 73
+// }
+
+await bt.close();
+```
+
+The daemon binary must be built first. Go is the only build dependency:
+
+```bash
+cd native/tls-client
+go build -o blacktip-tls .       # Linux / macOS
+go build -o blacktip-tls.exe .   # Windows
+```
+
+If the daemon binary is missing when `tlsRewriting: 'all'` is set, `bt.launch()` throws rather than silently falling back to native Chrome TLS that the caller didn't ask for.
+
+## Architecture
+
+The rewriter is installed as a Patchright/Playwright `context.route('**/*', handler)` hook, which is the high-level wrapper around CDP `Fetch.enable`. We use the route handler so we don't need to manage CDP sessions ourselves.
+
+For each intercepted request, the handler:
+
+1. Reads URL, method, headers, body via Playwright's `Request` API.
+2. Strips request headers Chrome's lifecycle owns: `Host`, `Content-Length`, `Connection`, `Keep-Alive`, `Transfer-Encoding`, etc.
+3. Calls `TlsSideChannel.fetch()` with the cleaned-up request — the daemon makes the upstream call with real Chrome TLS.
+4. Strips response headers Chrome re-computes: `Content-Length`, `Content-Encoding`, `Transfer-Encoding`, `Connection`, `Keep-Alive`.
+5. Multi-valued headers are joined: `Set-Cookie` with `\n` (so each cookie stays separate), everything else with `, `.
+6. Calls `route.fulfill({ status, headers, body })` with the daemon's response — the browser receives it as if Chrome had made the request itself.
+
+The daemon stays alive for the lifetime of the browser context. On `bt.close()`, the rewriter is uninstalled and the daemon is shut down via its existing `TlsSideChannel.close()` path.
+
+## Chrome flags
+
+When `tlsRewriting: 'all'` is set, BlackTip automatically launches Chrome with `--disable-quic` to force HTTP/1.1 and HTTP/2 only. This is required because Chrome handles QUIC at a layer below CDP Fetch — QUIC requests would bypass the rewriter entirely and present Chrome's native TLS to the wire. With QUIC disabled, every HTTP request flows through Fetch and through us.
+
+Real Chrome users disable QUIC routinely (corporate network policies, debugging) so this isn't a fingerprinting tell on its own. If you need QUIC for some reason (rare), set `tlsRewriting: 'off'` and use the v0.3.0 side-channel for the requests that matter most.
+
+## Limitations
+
+### WebSocket leaks
+
+Chrome handles WebSocket frames at a layer below CDP `Fetch.enable`. The initial HTTP `Upgrade: websocket` request can be intercepted, but the actual WebSocket frames after the upgrade go straight through Chrome's native TLS. The rewriter detects WebSocket upgrades, logs a warning, and falls through to `route.continue()` so the upgrade succeeds (and the WebSocket works) — but those frames present Chrome's host-OS TLS, not the daemon's.
+
+Mitigation: if your target uses WebSockets and you need full TLS rewriting on them, the only honest answer today is "use a proxy that handles WebSocket framing" (which is back to TCP-level MITM). The rewriter's `webSocketLeaks` stat counts how many you saw so you can decide whether to care.
+
+### Streaming responses
+
+CDP `Fetch.fulfillRequest` requires a complete body. The rewriter buffers each response fully before fulfilling, which is fine for HTML, JSON, CSS, JS, fonts, images, and typical web pages — but bad for video streams, large file downloads, and Server-Sent Events. For those, set `tlsRewriting: 'off'` and use the v0.3.0 side-channel selectively for the gating requests.
+
+### HTTP/3 / QUIC
+
+Disabled via `--disable-quic` automatically when the rewriter is on (see above). If a server only serves HTTP/3, the rewriter can't reach it.
+
+### Per-request overhead
+
+Each intercepted request adds 5–10ms of round-trip overhead through the daemon (measured: `avgDurationMs ≈ 70-100ms` for typical small responses, dominated by the actual upstream network latency). On a typical page with 50 subresources that's 250–500ms added to the total page load. Acceptable for stealth-critical use cases; not acceptable for high-throughput crawling.
+
+### Stats accounting
+
+`intercepted` may be slightly higher than `fulfilled + fellThrough + webSocketLeaks` (off by 1–5 on a typical page) when requests are aborted by Chrome's navigation lifecycle before the route handler completes. The functional behavior is correct — the page renders properly — but the counter doesn't perfectly account for the cancelled-in-flight cases. Don't use the stats for billing.
+
+## When to use which
+
+| Need | Use |
+|---|---|
+| Make a single gating request before launching the browser | `bt.fetchWithTls()` (v0.3.0 side-channel) |
+| Make sure every subresource also presents real Chrome TLS | `tlsRewriting: 'all'` (v0.5.0 rewriter) |
+| Cross-platform UA spoofing (Linux pretending to be Mac) | `tlsRewriting: 'all'` |
+| WebSocket-heavy app (chat, real-time stocks) | `tlsRewriting: 'off'` + selective side-channel |
+| Video streaming or large downloads | `tlsRewriting: 'off'` |
+| Maximum throughput crawling | `tlsRewriting: 'off'` |
+| Stealth-critical, throughput-flexible | `tlsRewriting: 'all'` |

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=

package/native/tls-client/main.go

@@ -0,0 +1,216 @@
+// BlackTip TLS side-channel daemon.
+//
+// Reads newline-delimited JSON requests from stdin, performs HTTP
+// requests with a real Chrome TLS fingerprint via bogdanfinn/tls-client,
+// and writes newline-delimited JSON responses to stdout.
+//
+// This is the v0.3.0 answer to the question: "what do I do when an edge
+// gates the very first request before BlackTip's browser has a session?"
+// You use this daemon to make the gating request — it presents a real
+// Chrome TLS ClientHello, real H2 frames, and real headers — capture
+// the cookies and tokens it gets back, and inject them into the
+// browser session before the user-driven flow continues.
+//
+// Wire format:
+//
+//   Request:  {"id":"<string>","url":"<string>","method":"<GET|POST|...>","headers":{"...":"..."},"body":"<string base64>","timeoutMs":15000,"profile":"chrome_133"}
+//   Response: {"id":"<string>","ok":true,"status":200,"headers":{"...":["...","..."]},"body":"<string base64>","finalUrl":"<string>","durationMs":123}
+//             OR
+//             {"id":"<string>","ok":false,"error":"<message>","durationMs":123}
+//
+// One JSON object per line in both directions. The Node parent reads
+// stdout line-by-line and matches responses by id. The daemon stays
+// alive across many requests so we don't pay subprocess startup cost
+// per call.
+package main
+
+import (
+	"bufio"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	http "github.com/bogdanfinn/fhttp"
+	tls_client "github.com/bogdanfinn/tls-client"
+	"github.com/bogdanfinn/tls-client/profiles"
+)
+
+type request struct {
+	ID        string            `json:"id"`
+	URL       string            `json:"url"`
+	Method    string            `json:"method"`
+	Headers   map[string]string `json:"headers"`
+	Body      string            `json:"body"`
+	TimeoutMs int               `json:"timeoutMs"`
+	Profile   string            `json:"profile"`
+}
+
+type response struct {
+	ID         string              `json:"id"`
+	OK         bool                `json:"ok"`
+	Status     int                 `json:"status,omitempty"`
+	Headers    map[string][]string `json:"headers,omitempty"`
+	Body       string              `json:"body,omitempty"`
+	FinalURL   string              `json:"finalUrl,omitempty"`
+	DurationMs int64               `json:"durationMs"`
+	Error      string              `json:"error,omitempty"`
+}
+
+// resolveProfile maps a profile name to a tls-client ClientProfile.
+// Defaults to the latest Chrome at the time of writing.
+func resolveProfile(name string) profiles.ClientProfile {
+	switch strings.ToLower(name) {
+	case "chrome_120":
+		return profiles.Chrome_120
+	case "chrome_124":
+		return profiles.Chrome_124
+	case "chrome_131":
+		return profiles.Chrome_131
+	case "chrome_133":
+		return profiles.Chrome_133
+	case "firefox_120":
+		return profiles.Firefox_120
+	case "safari_ios_16_0":
+		return profiles.Safari_IOS_16_0
+	default:
+		return profiles.Chrome_133
+	}
+}
+
+// buildClient constructs a tls-client with the requested profile and timeout.
+// We rebuild on every request because timeout is per-request and the cost
+// is negligible compared to the network round-trip.
+func buildClient(profile profiles.ClientProfile, timeoutMs int) (tls_client.HttpClient, error) {
+	if timeoutMs <= 0 {
+		timeoutMs = 15000
+	}
+	options := []tls_client.HttpClientOption{
+		tls_client.WithTimeoutSeconds(timeoutMs / 1000),
+		tls_client.WithClientProfile(profile),
+		tls_client.WithNotFollowRedirects(),
+	}
+	return tls_client.NewHttpClient(tls_client.NewNoopLogger(), options...)
+}
+
+func handle(req request) response {
+	start := time.Now()
+	durationFor := func() int64 { return time.Since(start).Milliseconds() }
+
+	if req.URL == "" {
+		return response{ID: req.ID, OK: false, Error: "url is required", DurationMs: durationFor()}
+	}
+	method := req.Method
+	if method == "" {
+		method = "GET"
+	}
+
+	client, err := buildClient(resolveProfile(req.Profile), req.TimeoutMs)
+	if err != nil {
+		return response{ID: req.ID, OK: false, Error: "buildClient: " + err.Error(), DurationMs: durationFor()}
+	}
+
+	var bodyReader io.Reader
+	if req.Body != "" {
+		decoded, decErr := base64.StdEncoding.DecodeString(req.Body)
+		if decErr != nil {
+			return response{ID: req.ID, OK: false, Error: "body base64 decode: " + decErr.Error(), DurationMs: durationFor()}
+		}
+		bodyReader = strings.NewReader(string(decoded))
+	}
+
+	httpReq, err := http.NewRequest(method, req.URL, bodyReader)
+	if err != nil {
+		return response{ID: req.ID, OK: false, Error: "NewRequest: " + err.Error(), DurationMs: durationFor()}
+	}
+
+	for k, v := range req.Headers {
+		httpReq.Header.Set(k, v)
+	}
+	// If the caller didn't set Accept-Language, fall back to a Chrome default.
+	if httpReq.Header.Get("Accept-Language") == "" {
+		httpReq.Header.Set("Accept-Language", "en-US,en;q=0.9")
+	}
+
+	resp, err := client.Do(httpReq)
+	if err != nil {
+		return response{ID: req.ID, OK: false, Error: "Do: " + err.Error(), DurationMs: durationFor()}
+	}
+	defer resp.Body.Close()
+
+	bodyBytes, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return response{ID: req.ID, OK: false, Error: "read body: " + err.Error(), DurationMs: durationFor()}
+	}
+
+	headers := make(map[string][]string, len(resp.Header))
+	for k, v := range resp.Header {
+		headers[k] = v
+	}
+
+	finalURL := req.URL
+	if resp.Request != nil && resp.Request.URL != nil {
+		finalURL = resp.Request.URL.String()
+	}
+
+	return response{
+		ID:         req.ID,
+		OK:         true,
+		Status:     resp.StatusCode,
+		Headers:    headers,
+		Body:       base64.StdEncoding.EncodeToString(bodyBytes),
+		FinalURL:   finalURL,
+		DurationMs: durationFor(),
+	}
+}
+
+func main() {
+	scanner := bufio.NewScanner(os.Stdin)
+	// Allow large request bodies (e.g. POSTed forms with file fields).
+	scanner.Buffer(make([]byte, 0, 64*1024), 16*1024*1024)
+
+	// Stdout writes are mutex-protected so concurrent handlers don't
+	// interleave their JSON lines.
+	var stdoutMu sync.Mutex
+	emit := func(r response) {
+		out, err := json.Marshal(r)
+		if err != nil {
+			out = []byte(fmt.Sprintf(`{"id":%q,"ok":false,"error":"marshal failed: %s"}`, r.ID, err.Error()))
+		}
+		stdoutMu.Lock()
+		defer stdoutMu.Unlock()
+		os.Stdout.Write(out)
+		os.Stdout.Write([]byte("\n"))
+	}
+
+	var wg sync.WaitGroup
+	for scanner.Scan() {
+		line := append([]byte(nil), scanner.Bytes()...)
+		if len(line) == 0 {
+			continue
+		}
+		var req request
+		if err := json.Unmarshal(line, &req); err != nil {
+			emit(response{ID: "", OK: false, Error: "unmarshal: " + err.Error()})
+			continue
+		}
+		// Handle requests concurrently — the Go TLS client is goroutine-safe.
+		wg.Add(1)
+		go func(r request) {
+			defer wg.Done()
+			emit(handle(r))
+		}(req)
+	}
+	if err := scanner.Err(); err != nil {
+		fmt.Fprintln(os.Stderr, "scan error:", err)
+		os.Exit(1)
+	}
+	// Wait for any in-flight requests to drain before exiting. Without
+	// this, closing stdin races the goroutines and the parent never
+	// sees the response.
+	wg.Wait()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rester159/blacktip",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Stealth browser instrument for AI agents. Real Chrome + patchright CDP stealth + human-calibrated behavioral simulation. Every action is indistinguishable from a human.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,8 +21,14 @@
     "dist",
     "README.md",
     "AGENTS.md",
+    "CHANGELOG.md",
     "LICENSE",
-    "examples"
+    "examples",
+    "docs",
+    "native/tls-client/main.go",
+    "native/tls-client/go.mod",
+    "native/tls-client/go.sum",
+    "scripts"
   ],
   "scripts": {
     "build": "tsc",