@rester159/blacktip 0.2.0 → 0.5.0

package/docs/akamai-sensor.md

@@ -0,0 +1,183 @@
+# Akamai sensor challenge solver (v0.5.0)
+
+`bt.solveAkamaiChallenge(url)` is the v0.5.0 answer to "I want to call Akamai-protected APIs from a sessionless TLS daemon, but the first request always 403s because Akamai gates everything behind a sensor data POST." Solve the challenge once in a real browser, get back the validated cookies plus a recommended header set, then replay arbitrary requests via `bt.fetchWithTls()` (or any other HTTP client) for as long as the cookies stay valid. **Empirically validated against OpenTable Akamai Bot Manager: 5/5 replay calls return 200 with real content. ~600ms per replay vs ~4s per browser launch.**
+
+## Why this isn't a pure-Go solver
+
+Reverse-engineering Akamai's `bm.js` to generate sensor data without a browser is intentionally hostile work and the maintenance economics are bad:
+
+1. **bm.js is heavily obfuscated.** OpenTable's current sensor JS is 26 KB of hex-encoded string array references with no recognizable function names. References to `gyroscope`, `hardwareConcurrency`, `selenium`, `Chrome`, `vendor`, `ShockwaveFlash` are scattered through it — clearly the sensor collector — but extracting them requires symbolic execution, not just regex.
+2. **Sensor data is encrypted with a runtime-derived key** that lives inside the obfuscated code. You can't just capture the POST body Chrome sends and replay it — the key changes per session.
+3. **Akamai rotates the obfuscation monthly.** A pure-Go reimplementation would be a 1–2 week reverse engineering project, and the result would rot in ~6 weeks. Bad ROI.
+
+What works instead, and what BlackTip ships in v0.5.0: launch a real BlackTip browser, navigate to the URL, let Akamai's bm.js execute naturally (real Chrome runs the JS, generates the sensor payload, POSTs it back), and capture the validated cookies. The caller then injects those cookies into thousands of sessionless TLS-daemon API calls until they expire.
+
+**This is NOT "no browser needed for Akamai." It IS "amortize browser cost across many subsequent API calls instead of paying it per request."** For most use cases that's the same thing — you pay one browser session per hour and run hundreds of API calls in between.
+
+## Quick start
+
+```typescript
+import { BlackTip } from '@rester159/blacktip';
+
+const bt = new BlackTip({ logLevel: 'info' });
+await bt.launch();
+
+// 1. Solve the Akamai challenge in the browser. ~15s.
+const solved = await bt.solveAkamaiChallenge(
+  'https://www.opentable.com/booking/restref/availability?rid=76651&restref=76651&partySize=2&dateTime=2026-04-11T19:00',
+);
+
+console.log('Validated:', solved.validated);
+console.log('Akamai cookies:', solved.cookies.map(c => c.name));
+// → [ 'bm_ss', 'bm_so', 'bm_mi', 'bm_sz', 'ak_bmsc', 'bm_s', 'bm_sv', '_abck' ]
+
+// 2. Replay arbitrary requests via the TLS daemon. ~600ms each, no browser.
+for (let i = 0; i < 100; i++) {
+  const resp = await bt.fetchWithTls({
+    url: 'https://www.opentable.com/api/some-endpoint',
+    headers: solved.recommendedHeaders, // Cookie + Sec-Ch-Ua + Sec-Fetch-* baked in
+  });
+  console.log('Call', i, '→', resp.status);
+}
+
+await bt.close();
+```
+
+## Result shape
+
+```typescript
+interface AkamaiChallengeResult {
+  /**
+   * True when EITHER:
+   *   - _abck reached validated state (~0~), OR
+   *   - The page rendered without an Akamai block (sensor not enforced).
+   *
+   * Akamai's sensor validation is only enforced when other signals
+   * (TLS, IP, behavior) look suspicious. For real-Chrome sessions on
+   * residential connections, Akamai often admits the request without
+   * ever requiring the JS-layer sensor POST.
+   */
+  validated: boolean;
+
+  /**
+   * Actual sensor validation state:
+   *   0  → validated as human (gold standard)
+   *   -1 → sensor not enforced (page admitted without it)
+   *   1+ → flagged as bot
+   *   null → no _abck cookie set (target may not be Akamai-protected)
+   */
+  abckState: -1 | 0 | 1 | null;
+
+  /** The full _abck cookie value at the end of the wait window. */
+  abckValue: string | null;
+
+  /** Whether the rendered page is the Akamai Access Denied block page. */
+  blocked: boolean;
+
+  /** All Akamai-related cookies, ready to inject into other sessions. */
+  cookies: Array<{ name: string; value: string; domain: string; path: string }>;
+
+  /**
+   * Pre-built header set for replay calls. Includes Cookie, User-Agent,
+   * Accept, Accept-Language, Sec-Ch-Ua, Sec-Ch-Ua-Mobile, Sec-Ch-Ua-Platform,
+   * Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site, Sec-Fetch-User,
+   * Upgrade-Insecure-Requests. Pass directly to `bt.fetchWithTls()`.
+   *
+   * Replays without these headers will 403 even with valid cookies —
+   * Akamai validates the full request shape, not just the cookie jar.
+   */
+  recommendedHeaders: Record<string, string>;
+
+  finalUrl: string;
+  title: string;
+  durationMs: number;
+  notes: string[];
+}
+```
+
+## The cost amortization story
+
+OpenTable's Gjelina booking endpoint, measured on a residential connection:
+
+| Approach | Cost per call | 100 calls |
+|---|---|---|
+| Browser launch + navigate per call | ~4s | ~400s |
+| `solveAkamaiChallenge` once + 100 daemon replays | 15s + 100×0.6s = 75s | **75s** |
+| **Speedup** | | **~5.3x** |
+
+Larger N gets better. At 1,000 calls, it's 15s + 600s = 615s vs 4,000s — almost 7x. The crossover is at ~5 calls (below that, browser-per-call is faster because the solve overhead dominates).
+
+## What "validated" actually means
+
+Akamai's sensor validation has three observable states encoded in the second `~`-delimited field of the `_abck` cookie:
+
+| `_abck` state | Meaning | What you can do |
+|---|---|---|
+| `~0~` | Sensor data validated as human | Maximum trust — replay anything |
+| `~-1~` | Sensor not enforced (Akamai admitted on other signals) | Replay safely — same as `~0~` for most APIs |
+| `~1~` (or higher) | Sensor flagged as bot | Session burned — solve again with a different identity |
+
+The interesting case is `~-1~`. On every empirical test against OpenTable from a residential connection, Akamai admitted the request without ever requiring sensor validation — `_abck` stayed at `~-1~` but the page rendered fine and the cookies worked for daemon replays. This is consistent with Akamai's own marketing: the sensor JS is one layer of a multi-factor decision, and high-confidence requests (good TLS, good IP, real Chrome behavior) get admitted without it.
+
+That's why `validated` is `true` for both `~0~` and `~-1~` outcomes — both unlock the replay path.
+
+## Replay headers — why all of them matter
+
+The first thing I tried after solving was naive: solve in browser, copy cookies, pass them through `Cookie:` header to the daemon. **It 403'd.** Then I added the full Chrome header set: `Sec-Ch-Ua`, `Sec-Ch-Ua-Mobile`, `Sec-Ch-Ua-Platform`, `Sec-Fetch-Dest`, `Sec-Fetch-Mode`, `Sec-Fetch-Site`, `Sec-Fetch-User`, `Upgrade-Insecure-Requests`. **It returned 200.**
+
+Akamai is validating the full request shape, not just the cookie jar. Without the Sec-Fetch-* headers, the request looks like a programmatic fetch and Akamai blocks it even with valid cookies. With them, the request looks like a navigation from a real Chrome and Akamai admits it.
+
+The `recommendedHeaders` field on the solver result includes all of these. Don't strip them; pass the whole object to `bt.fetchWithTls({ url, headers: solved.recommendedHeaders })`.
+
+## Combining with IdentityPool
+
+If you're running long-lived flows with identity rotation, the natural pattern is to attach the solved Akamai cookies to an IdentityPool snapshot:
+
+```typescript
+import { BlackTip, IdentityPool } from '@rester159/blacktip';
+
+const pool = new IdentityPool({ storePath: './.bt/identities.json' });
+const identity = pool.acquire('opentable.com')!;
+
+const config = pool.applyToConfig(identity);
+const bt = new BlackTip(config);
+await bt.launch();
+await pool.restoreSnapshot(bt, identity);
+
+// Solve Akamai once for this identity
+const solved = await bt.solveAkamaiChallenge('https://www.opentable.com/booking/...');
+if (!solved.validated) {
+  pool.markBurned(identity.id, 'Akamai blocked', 'opentable.com');
+  return;
+}
+
+// Save the post-solve session state into the identity for next time
+await pool.captureSnapshot(bt, identity);
+
+// Run N daemon replays. When _abck eventually expires, re-solve.
+for (let i = 0; i < 100; i++) {
+  const resp = await bt.fetchWithTls({
+    url: 'https://www.opentable.com/api/...',
+    headers: solved.recommendedHeaders,
+  });
+  // ...
+}
+
+await bt.close();
+```
+
+Now your identity is durable: cookies + storage + solved Akamai state, all persisted, ready to resume tomorrow without re-solving.
+
+## Limitations
+
+- **Still requires a browser to solve.** This is the whole point of the architecture decision documented above. If you need pure-Go API access without ever launching a browser, you're going to write a lot of obfuscation reverse-engineering code that breaks every 6 weeks. v0.5.0 doesn't ship that path.
+- **Cookies expire.** Akamai's session window is typically ~1 hour for the validated state. After that, replays start returning 403 again and you need to re-solve. Re-solving from the same browser context is fast (~3s on subsequent calls because the browser already has the prior state).
+- **`_abck` flagged state means session burned.** If `abckState === 1`, the cookies are useless — Akamai marked you as a bot and even the browser session won't recover. You need a fresh BlackTip launch with a different identity (different proxy, fresh user data dir, possibly different device profile).
+- **Per-domain.** This solver is tested against OpenTable. The pattern works against any Akamai Bot Manager target but the specific URL format and timing may vary. Adjust `dwellMsBeforePolling` and `timeoutMs` per-target.
+
+## See also
+
+- `docs/tls-side-channel.md` — the underlying `bt.fetchWithTls()` daemon
+- `docs/tls-rewriting.md` — the v0.5.0 full-rewriting mode (TLS rewriter intercepts every browser request)
+- `docs/identity-pool.md` — long-running session and identity rotation
+- `docs/akamai-bypass.md` — the v0.2.0 plan that documents Akamai's detection layer stack and the L016 fix that opened the door

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.