@rester159/blacktip 0.2.0 → 0.4.0

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.4.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",

package/scripts/fit-cmu-keystroke.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Fit a behavioral profile against the real CMU Keystroke Dynamics
+ * dataset and report a held-out validation result.
+ *
+ * This is the v0.3.0 calibration validation script. It:
+ *
+ *   1. Loads `data/cmu-keystroke/DSL-StrongPasswordData.csv` (51 subjects
+ *      × 8 sessions × 50 reps = 20,400 phrases of `.tie5Roanl`).
+ *   2. Splits subjects 80/20 into training and held-out sets.
+ *   3. Fits a `CalibratedProfile` against the training subjects.
+ *   4. Reports the fitted distribution parameters.
+ *   5. Computes a Kolmogorov–Smirnov-style distribution-similarity score
+ *      (max CDF distance) of the fit against (a) the training set,
+ *      (b) the held-out set, and (c) BlackTip's canonical HUMAN_PROFILE.
+ *      A good fit beats the canonical profile on the held-out set.
+ *   6. Writes the resulting profile to
+ *      `data/cmu-keystroke/calibrated-profile.json` so users can load
+ *      it in their own code without re-running the fit every time.
+ *
+ * Run with: node scripts/fit-cmu-keystroke.mjs
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseCmuKeystrokeCsv } from '../dist/behavioral/parsers.js';
+import { fitTypingDynamics, fitMouseDynamics, deriveProfileConfig } from '../dist/behavioral/calibration.js';
+import { HUMAN_PROFILE } from '../dist/behavioral-engine.js';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const csvPath = join(root, 'data', 'cmu-keystroke', 'DSL-StrongPasswordData.csv');
+const outPath = join(root, 'data', 'cmu-keystroke', 'calibrated-profile.json');
+
+console.log('Loading CMU CSV from', csvPath);
+const csv = readFileSync(csvPath, 'utf-8');
+const allSessions = parseCmuKeystrokeCsv(csv);
+console.log(`Parsed ${allSessions.length} typing sessions (each is one rep of .tie5Roanl)`);
+
+if (allSessions.length === 0) {
+  console.error('No sessions parsed — check CSV format');
+  process.exit(1);
+}
+
+// The phrase has 11 keys; sanity check the first session.
+const first = allSessions[0];
+console.log(`First session: ${first.keystrokes.length} keystrokes, phrase=${first.phrase}`);
+if (first.keystrokes.length !== 11) {
+  console.error(`Expected 11 keystrokes per session, got ${first.keystrokes.length}`);
+  process.exit(1);
+}
+
+// CMU subjects are encoded in the source CSV but not exposed by the
+// parser (which throws away subject IDs). For an honest 80/20 train/test
+// split we re-read the CSV's first column ourselves.
+const lines = csv.trim().split(/\r?\n/);
+const subjectsInOrder = lines.slice(1).map((l) => l.split(',')[0]);
+const uniqueSubjects = [...new Set(subjectsInOrder)];
+console.log(`Found ${uniqueSubjects.length} unique subjects`);
+
+// Deterministic 80/20 split — sort then slice, so re-runs are stable.
+const trainSubjects = new Set(uniqueSubjects.slice(0, Math.floor(uniqueSubjects.length * 0.8)));
+const testSubjects = new Set(uniqueSubjects.slice(Math.floor(uniqueSubjects.length * 0.8)));
+console.log(`Train: ${trainSubjects.size} subjects, Test: ${testSubjects.size} subjects`);
+
+const trainSessions = [];
+const testSessions = [];
+for (let i = 0; i < allSessions.length; i++) {
+  const subj = subjectsInOrder[i];
+  if (trainSubjects.has(subj)) trainSessions.push(allSessions[i]);
+  else if (testSubjects.has(subj)) testSessions.push(allSessions[i]);
+}
+console.log(`Train sessions: ${trainSessions.length}, Test sessions: ${testSessions.length}`);
+
+// Fit
+console.log('\nFitting typing dynamics on training set...');
+const trainTyping = fitTypingDynamics(trainSessions);
+console.log(`  Hold time:   mean=${trainTyping.holdTime.mean.toFixed(1)}ms  p5=${trainTyping.holdTime.p5.toFixed(1)}  p50=${trainTyping.holdTime.p50.toFixed(1)}  p95=${trainTyping.holdTime.p95.toFixed(1)}`);
+console.log(`  Flight time: mean=${trainTyping.flightTime.mean.toFixed(1)}ms  p5=${trainTyping.flightTime.p5.toFixed(1)}  p50=${trainTyping.flightTime.p50.toFixed(1)}  p95=${trainTyping.flightTime.p95.toFixed(1)}`);
+console.log(`  Digraphs fit: ${Object.keys(trainTyping.digraphFlightTime).length}`);
+console.log(`  Mistake rate: ${(trainTyping.mistakeRate * 100).toFixed(2)}%`);
+
+// Mouse fit isn't applicable to CMU keystroke data — leave it at the
+// canonical defaults so the derived ProfileConfig is well-formed.
+const mouseFit = fitMouseDynamics([]);
+
+// Held-out evaluation: extract raw flight and hold samples from each set,
+// then compare empirical CDFs.
+const flightsFromSessions = (sessions) => {
+  const out = [];
+  for (const s of sessions) for (let i = 1; i < s.keystrokes.length; i++) out.push(s.keystrokes[i].flightTimeMs);
+  return out;
+};
+const holdsFromSessions = (sessions) => {
+  const out = [];
+  for (const s of sessions) for (const k of s.keystrokes) out.push(k.holdTimeMs);
+  return out;
+};
+
+const ksDistance = (a, b) => {
+  // Empirical KS distance: max |F_a(x) - F_b(x)| over the merged sample set.
+  const sortedA = [...a].sort((x, y) => x - y);
+  const sortedB = [...b].sort((x, y) => x - y);
+  const all = [...new Set([...sortedA, ...sortedB])].sort((x, y) => x - y);
+  const cdf = (sorted, x) => {
+    let lo = 0, hi = sorted.length;
+    while (lo < hi) { const mid = (lo + hi) >> 1; if (sorted[mid] <= x) lo = mid + 1; else hi = mid; }
+    return lo / sorted.length;
+  };
+  let maxDiff = 0;
+  for (const x of all) {
+    const d = Math.abs(cdf(sortedA, x) - cdf(sortedB, x));
+    if (d > maxDiff) maxDiff = d;
+  }
+  return maxDiff;
+};
+
+const trainFlights = flightsFromSessions(trainSessions);
+const testFlights = flightsFromSessions(testSessions);
+const trainHolds = holdsFromSessions(trainSessions);
+const testHolds = holdsFromSessions(testSessions);
+
+// Synthesize samples from BlackTip's canonical profile to compare against.
+// HUMAN_PROFILE.typingSpeedMs is a [min, max] uniform-ish range — sample
+// 5000 values uniformly to build a synthetic distribution.
+const sampleUniform = (lo, hi, n) => {
+  const out = [];
+  for (let i = 0; i < n; i++) out.push(lo + Math.random() * (hi - lo));
+  return out;
+};
+const canonicalFlights = sampleUniform(HUMAN_PROFILE.typingSpeedMs[0], HUMAN_PROFILE.typingSpeedMs[1], 5000);
+const canonicalHolds = sampleUniform(HUMAN_PROFILE.clickDwellMs?.[0] ?? 40, HUMAN_PROFILE.clickDwellMs?.[1] ?? 100, 5000);
+
+// Synthesize "calibrated" samples from the fitted distribution by
+// sampling within [p5, p95]. This mirrors what BehavioralEngine will
+// actually emit when configured with the fitted ProfileConfig.
+const calibratedFlights = sampleUniform(trainTyping.flightTime.p5, trainTyping.flightTime.p95, 5000);
+const calibratedHolds = sampleUniform(trainTyping.holdTime.p5, trainTyping.holdTime.p95, 5000);
+
+const ksCanonicalFlight = ksDistance(testFlights, canonicalFlights);
+const ksCalibratedFlight = ksDistance(testFlights, calibratedFlights);
+const ksCanonicalHold = ksDistance(testHolds, canonicalHolds);
+const ksCalibratedHold = ksDistance(testHolds, calibratedHolds);
+
+console.log('\n=== Held-out KS distance (lower = closer to real human distribution) ===');
+console.log(`Flight time:`);
+console.log(`  Canonical HUMAN_PROFILE [${HUMAN_PROFILE.typingSpeedMs[0]}, ${HUMAN_PROFILE.typingSpeedMs[1]}]ms:  KS=${ksCanonicalFlight.toFixed(4)}`);
+console.log(`  Calibrated [p5=${trainTyping.flightTime.p5.toFixed(0)}, p95=${trainTyping.flightTime.p95.toFixed(0)}]ms:        KS=${ksCalibratedFlight.toFixed(4)}`);
+console.log(`  Improvement: ${(ksCanonicalFlight - ksCalibratedFlight).toFixed(4)} (${((1 - ksCalibratedFlight / ksCanonicalFlight) * 100).toFixed(1)}% closer)`);
+console.log(`Hold time:`);
+console.log(`  Canonical clickDwellMs [${HUMAN_PROFILE.clickDwellMs?.[0]}, ${HUMAN_PROFILE.clickDwellMs?.[1]}]ms:  KS=${ksCanonicalHold.toFixed(4)}`);
+console.log(`  Calibrated [p5=${trainTyping.holdTime.p5.toFixed(0)}, p95=${trainTyping.holdTime.p95.toFixed(0)}]ms:           KS=${ksCalibratedHold.toFixed(4)}`);
+console.log(`  Improvement: ${(ksCanonicalHold - ksCalibratedHold).toFixed(4)} (${((1 - ksCalibratedHold / ksCanonicalHold) * 100).toFixed(1)}% closer)`);
+
+const profileConfig = deriveProfileConfig(mouseFit, trainTyping);
+const calibrated = {
+  name: 'cmu-keystroke-2009',
+  source: 'CMU Keystroke Dynamics dataset (Killourhy & Maxion 2009), 80% subject train split',
+  fittedAt: new Date().toISOString(),
+  trainSubjects: trainSubjects.size,
+  testSubjects: testSubjects.size,
+  trainSessions: trainSessions.length,
+  testSessions: testSessions.length,
+  validation: {
+    flightTime: {
+      canonicalKsDistance: ksCanonicalFlight,
+      calibratedKsDistance: ksCalibratedFlight,
+      improvementRatio: 1 - ksCalibratedFlight / ksCanonicalFlight,
+    },
+    holdTime: {
+      canonicalKsDistance: ksCanonicalHold,
+      calibratedKsDistance: ksCalibratedHold,
+      improvementRatio: 1 - ksCalibratedHold / ksCanonicalHold,
+    },
+  },
+  fits: {
+    typing: trainTyping,
+  },
+  profileConfig,
+};
+
+writeFileSync(outPath, JSON.stringify(calibrated, null, 2));
+console.log(`\nWrote calibrated profile to ${outPath}`);
+console.log(`\nUse it via:`);
+console.log(`  import calibrated from './data/cmu-keystroke/calibrated-profile.json' with { type: 'json' };`);
+console.log(`  const bt = new BlackTip({ behaviorProfile: calibrated.profileConfig });`);