@rester159/blacktip 0.1.0

package/AGENTS.md

@@ -0,0 +1,249 @@
+# AGENTS.md — BlackTip for AI agents
+
+**Read this before driving BlackTip.** This file is shipped with every BlackTip install and is designed to be auto-loaded by agent frameworks (Claude Code, Cursor, aider, etc.) as context for the consuming project. If you are an LLM-backed agent, treat this as the user manual.
+
+BlackTip is a browser instrument. YOU are the agent. BlackTip provides the hands; you provide the brain.
+
+---
+
+## The core loop
+
+1. **Read the source documents first.** If the user gave you a PDF, image, or file to submit, read it BEFORE touching the browser. Extract names, dates, amounts, IDs. Never guess.
+2. **Start the server.** `npx blacktip serve` (or create a `BlackTip` instance and call `await bt.serve(port)`).
+3. **Send one command at a time.** After each command, read the returned bundle: `{ok, result, url, title, screenshotPath, screenshotB64, durationMs}`.
+4. **Look at the screenshot.** The returned `screenshotB64` (or the saved file at `screenshotPath`) is the ground truth for what the page currently looks like. Do NOT pre-script a sequence of steps — look, decide, act, repeat.
+5. **Ask when uncertain.** Don't guess credentials, form values, patient names, account types, or confirmation decisions. Ask the user.
+
+---
+
+## Rules (always follow)
+
+### 1. Read input documents before opening the browser
+
+If the user provides a bill, form, or screenshot, extract all relevant data first. Every minute spent understanding the source saves ten minutes of corrections in the browser. This rule is non-negotiable.
+
+### 2. Screenshot between every decision
+
+BlackTip's `send` response includes a base64 screenshot of the page after each command. Look at it before deciding the next step. The page may have changed, loaded slowly, or shown an error you didn't expect. Do NOT assume the next step works because the last one did.
+
+### 3. Use `clickText()` for visible text, `click()` for selectors
+
+- `bt.clickText("Sign in", { nth: 0 })` — uses Playwright's locator API. Correctly handles React, Angular, Okta, and other framework-driven components. Prefer this over CSS selectors when the text is visible on the page.
+- `bt.click("#submit-btn")` — use when you have a reliable CSS or XPath selector.
+- `bt.clickRole("button", { name: "Submit" })` — use for ARIA-role-based matches.
+
+All three auto-detect high-importance actions (submit, pay, confirm, place order, delete, etc.) and apply longer pre-action hesitation. You can override with `importance: 'low' | 'normal' | 'high'`.
+
+### 4. Use `paste: true` for form filling
+
+`bt.type(selector, text, { paste: true })` uses Playwright's `fill()` which correctly triggers React/Angular synthetic events. This is the fast path and should be your default for form fields.
+
+Without `paste: true`, BlackTip simulates keystroke-by-keystroke typing with digraph-aware timing and occasional typos. Slower but looks more human. Use when a site profiles typing dynamics.
+
+### 5. Use `inspect()` to diagnose selectors
+
+When a click or type fails, use `bt.inspect(selector)` before retrying. It returns `{exists, visible, tagName, text, attributes, boundingBox}` — one call replaces several hand-written `executeJS` queries.
+
+### 6. Use `listOptions()` for Angular/React custom dropdowns
+
+Custom dropdowns are NOT `<select>` elements. Pattern:
+
+```js
+await bt.click("#state-dropdown_button");               // Open the combobox
+const options = await bt.listOptions("#state-dropdown"); // List options
+// options: [{id: "state-dropdown_option-0", text: "Alabama"}, ...]
+await bt.click(options.find(o => o.text === "California").id);
+```
+
+### 7. Use `waitForStable()` instead of fixed sleeps
+
+Don't write `await new Promise(r => setTimeout(r, 3000))`. That's always wrong — either too short (you miss the event) or too long (you waste time). Use:
+
+- `await bt.waitForStable({ networkIdleMs: 500, domIdleMs: 500 })` — page has settled
+- `await bt.waitForText("Success", { timeout: 10000 })` — wait for a specific string
+- `await bt.waitFor("#some-selector", { timeout: 10000 })` — wait for an element
+
+### 8. Check `didRequestFireSince` before retrying risky clicks
+
+If a click might have burned a rate-limited or lockout-protected attempt (password, 2FA, payment), check whether the submit actually reached the server:
+
+```js
+await bt.click(".submit-password");
+const submitted = await bt.didRequestFireSince(/idp\/idx\/challenge\/answer/, 3000);
+if (!submitted) {
+  // The click didn't fire. Safe to retry.
+} else {
+  // It DID fire. Check if it succeeded before retrying.
+}
+```
+
+This is how you avoid locking an account after a "did my click work?" moment.
+
+### 9. Use `dismissOverlays()` proactively on sites with chat widgets
+
+Chat widgets, cookie banners, and "we value your feedback" modals intercept clicks. `bt.dismissOverlays()` hides known overlay patterns (Intercom, Drift, Zendesk, OneTrust, Medallia, generic cookie consent) and returns the count hidden. Call it once after navigation on sites that have these, then proceed normally.
+
+BlackTip's `click` / `clickText` / `clickRole` also auto-detect interception and auto-dismiss overlays before retrying, so in most cases you don't need to call it explicitly.
+
+### 10. MFA: use `pauseForInput`
+
+When you hit an MFA / OTP / verification code prompt:
+
+```js
+await bt.click(".send-sms-button");
+const code = await bt.pauseForInput({
+  prompt: 'Enter the SMS code sent to your phone',
+  validate: /^\d{6}$/,
+  timeoutMs: 300_000,
+});
+await bt.type('input[name="code"]', code, { paste: true });
+await bt.click(".verify");
+```
+
+The BlackTip server sends a `{paused:true, pauseId, prompt}` frame to the client. The client (you) relays the prompt to the user, collects their answer, and resumes with:
+
+```bash
+npx blacktip resume <pauseId> "<value>"
+```
+
+### 11. Fail fast
+
+Use `timeout: 10000` and `retryAttempts: 2` as defaults. If an action fails, inspect the page with `bt.inspect()` and a screenshot rather than retrying blindly. Blind retries on lockout-protected forms burn attempts you cannot get back.
+
+### 12. Ask before destructive or irreversible actions
+
+Before clicking Submit on a form that can't be unsent (insurance claim, payment, purchase, account deletion, account creation with verified email), **stop and ask the user to confirm**. Show them the filled-in state from the screenshot. Wait for an explicit "confirmed" / "submit" / "go" before proceeding.
+
+### 13. Never guess secrets
+
+Passwords, MFA codes, payment details, SSNs, routing numbers, patient information — if the user didn't give it to you explicitly, ask. Don't infer from memory, don't infer from session state, don't pattern-match from other accounts.
+
+---
+
+## Common mistakes (don't repeat these)
+
+- **Pre-scripting an entire flow.** Breaks on the first unexpected page state. Always look at the screenshot after each step.
+- **Using `executeJS("el.click()")` for React/Okta buttons.** DOM clicks don't trigger framework event handlers. Use `clickText()` or `click()` which dispatch real pointer events.
+- **Not reading screenshots between actions.** The most common failure mode. If you're not looking at the screenshot, you're flying blind.
+- **Guessing form values instead of reading source documents.** Led to submitting the wrong patient name on an Anthem claim during development.
+- **Long timeouts (30s+).** You're waiting on a page that's already broken. Fail fast, inspect, adapt.
+- **Treating data: URLs as fully functional.** `patchright` blocks inline `<script>` execution on `data:` URLs as a stealth measure. Use `bt.executeJS()` after navigate to set up page state, or use a real HTTP server for fixtures.
+- **Retrying a failed login without checking `didRequestFireSince`.** You might have already burned an attempt without realizing it.
+- **Calling `.removeAllListeners()` with no argument.** It removes BlackTip's default `error` handler and Node's EventEmitter will crash on the next emitted error. Use `.removeAllListeners('action')` per-event instead.
+- **Not clearing prior drafts on form-heavy sites.** Some sites (Anthem, insurance portals) save drafts automatically. Check for and delete stale drafts before starting a new submission if the site supports it.
+- **Assuming BlackTip handles headless.** It doesn't. Every profile is headful. `headless: true` in config is ignored.
+
+---
+
+## Decision tree: common situations
+
+**"I clicked Next but the page didn't change."**
+
+1. Take a new screenshot via `bt.screenshot({path:'shot.png'})`. Look carefully — sometimes the page DID change and the error is a banner on top of the same layout.
+2. Check the URL: `bt.executeJS('location.href')`.
+3. Check if a request fired: `bt.didRequestFireSince(/your-endpoint/, 5000)`.
+4. If no request fired, the click was swallowed. Try `bt.dismissOverlays()` then click again, or use a direct CSS selector.
+5. If a request DID fire and the URL didn't change, there's an error on the page. `bt.extractText('body')` or look at the screenshot for error messaging.
+
+**"I can't find the selector I need."**
+
+1. `bt.inspect('#my-guess')` — verify what you think exists actually does.
+2. `bt.executeJS("[...document.querySelectorAll('button')].map(b => ({id: b.id, text: b.textContent.trim().slice(0,40)}))")` — enumerate candidates.
+3. For dropdowns, `bt.listOptions('#dropdown-id')` gets the Angular-style option ids.
+4. Try `bt.clickText("visible text")` as a fallback — often easier than finding the right CSS.
+
+**"There's a chat widget blocking my click."**
+
+1. `bt.dismissOverlays()` — returns `{hidden: N, selectors: [...]}`.
+2. Retry the click. BlackTip's click functions also auto-dismiss before falling back to force-click, so you usually don't need step 1.
+
+**"I'm about to click Submit on something important."**
+
+1. Take a screenshot first. Read it carefully.
+2. Summarize to the user what's about to happen (which patient, which amount, which destination).
+3. Wait for explicit confirmation.
+4. Only then click. Use `importance: 'high'` is auto-applied for buttons labeled Submit/Pay/Confirm, so you don't need to pass it manually.
+
+**"The flow hits MFA."**
+
+1. Click the "send code" button.
+2. Call `bt.pauseForInput({prompt: 'Enter SMS code', validate: /^\d{6}$/})`.
+3. The BlackTip server forwards the prompt to your client. You relay it to the user.
+4. When the user provides the code, call `npx blacktip resume <pauseId> "<code>"` (or send `RESUME <id>\n<value>` to the TCP socket).
+5. The paused command resumes with the code and you proceed.
+
+**"I'm uncertain whether a previous step succeeded."**
+
+Don't retry blindly. Use:
+- `bt.didRequestFireSince(pattern, ms)` for network-level confirmation
+- `bt.waitForText(expectedText, {timeout})` for content-level confirmation
+- `bt.inspect(selector).attributes` for state-level confirmation
+
+---
+
+## Server mode protocol
+
+Every `send` returns a JSON bundle (one line, DELIMITER `\n__END__\n`):
+
+```json
+{
+  "ok": true,
+  "result": <return value of the JS command, if any>,
+  "url": "https://current.page/",
+  "title": "Current Page Title",
+  "screenshotPath": "shot.png",
+  "screenshotB64": "<base64 PNG>",
+  "screenshotBytes": 41234,
+  "durationMs": 432
+}
+```
+
+On error:
+
+```json
+{
+  "ok": false,
+  "error": "Error message",
+  "url": "https://where.it.failed/",
+  "screenshotPath": "shot.png",
+  "screenshotB64": "<base64 PNG>",
+  "durationMs": 1234
+}
+```
+
+On pause:
+
+```json
+{
+  "ok": true,
+  "paused": true,
+  "pauseId": "pause-1712345678-12345",
+  "prompt": "Enter the SMS code"
+}
+```
+
+You respond with a `RESUME <pauseId>\n<value>` frame (ended with `\n__END__\n`) and the paused command continues.
+
+Batch mode accepts a `BATCH\n<json array of commands>` frame and returns `{ok, bundles: [bundle, bundle, ...]}` — useful for pipelining linear flows without per-command round trips.
+
+---
+
+## Behavioral knobs
+
+- `behaviorProfile: 'human'` — realistic timings (default for agent use)
+- `behaviorProfile: 'scraper'` — faster, less human, used in tests
+- `importance: 'high'` on `click` / `clickText` / `type` — longer pre-action hesitation. Auto-applied when button text matches common submit/pay/confirm patterns.
+- `bt.waitForStable({networkIdleMs: 500, domIdleMs: 500})` — better than fixed sleeps
+- `bt.generateReadingPause(textLength)` — estimate how long a human would take to read a block of text, returned as milliseconds
+
+---
+
+## Things BlackTip will not do for you
+
+- **It will not log you in.** You tell it the username and password.
+- **It will not read your SMS.** It pauses and asks you via `pauseForInput`.
+- **It will not solve captchas.** You integrate a solver if needed.
+- **It will not write tests for your flow.** That's still your job.
+- **It will not understand intent.** `bt.clickText("Submit")` clicks "Submit" — it doesn't verify that clicking "Submit" is the right thing to do in your context.
+
+If you want an opinion from the tool, you're asking the wrong tool. BlackTip provides primitives; the agent is the planner.

package/LICENSE

@@ -0,0 +1,38 @@
+MIT License
+
+Copyright (c) 2026 BlackTip Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+ACCEPTABLE USE NOTICE
+
+BlackTip is a dual-use tool. It is designed for authorized security testing,
+security research, browser fingerprinting research, your own accounts on
+services whose Terms of Service you have accepted, legitimate automation where
+the site's ToS permits automated access, and defensive anti-bot development.
+
+It is NOT designed for unauthorized access, fraud, circumventing paywalls,
+scraping sites that explicitly forbid automation, identity-related offenses,
+or any activity that would violate computer fraud laws in your jurisdiction.
+
+The authors disclaim responsibility for misuse. By using this software, you
+represent that your use is lawful and consistent with the terms of service
+of any site you access.

package/README.md

@@ -0,0 +1,234 @@
+# BlackTip
+
+**Stealth browser instrument for AI agents.** Real Chrome + patchright CDP stealth + human-calibrated behavioral simulation. BlackTip is the hands, you (or your agent) are the brain.
+
+BlackTip is not an agent. It does not parse natural language, does not plan, and does not decide what to click. It exposes primitives — `navigate`, `click`, `type`, `scroll`, `screenshot`, `waitForStable` — and wraps every action in human behavior that defeats bot detection.
+
+**If you are an AI agent reading this, load `AGENTS.md` next.** It contains the rules, patterns, and common mistakes you need to know before driving BlackTip. The `README.md` is for humans evaluating the tool; `AGENTS.md` is for agents using it.
+
+---
+
+## What's different about BlackTip
+
+Most open-source "stealth browser" projects are Playwright plus a JavaScript shim that overrides `navigator.webdriver`. That's table stakes and it's 2018-era thinking. Modern bot detection fingerprints the TLS ClientHello, the HTTP/2 frame order, the GPU through ANGLE, the canvas shader output, and — increasingly — your mouse dynamics and keystroke timing.
+
+BlackTip's architecture:
+
+| Layer | Approach | What it defeats |
+|---|---|---|
+| TLS / HTTP/2 fingerprint | Uses real Chrome Stable via Playwright `channel: 'chrome'`. ClientHello is genuine Chrome's, including rotating GREASE. | JA3 / JA4 / Akamai HTTP/2 fingerprinting |
+| CDP / webdriver detection | `patchright` drop-in replacement for Playwright. Patches `Runtime.Enable` leak, Error stack hooks, `console.debug` hooks, automation string artifacts. | CreepJS headless/stealth panels, bot.sannysoft.com's webdriver check |
+| GPU / canvas / audio | Real GPU rendered through ANGLE (no SwiftShader). Seeded canvas noise and audio noise tied to profile name for cross-session stability. | Canvas fingerprinting, audio fingerprinting, WebGL identification |
+| Behavioral fidelity | Bézier mouse paths with Fitts' Law movement time, digraph-aware typing with typos/corrections, scroll deceleration, importance-scaled hesitation on submit/pay/confirm buttons, reading pause estimation. Calibratable against real mouse-dynamics datasets. | Behavioral biometrics (BioCatch, NuData, SecuredTouch) |
+| Click robustness | Live bounding-box re-read before click (DOM reflow resistance), pre-click overlay detection, automatic overlay dismissal, force-click fallback. | Dynamic pages, chat widgets, cookie banners |
+| Agent interface | TCP serve mode with bundled JSON responses (URL, title, screenshot, result in one frame). Batch command support. pause/resume for MFA. `--file` / `--stdin` inputs to eliminate shell-escape hell. | Orchestration overhead that makes agents slow |
+
+**Detector scoreboard** (live as of last run; see `planning/baselines/` for timestamped artifacts):
+
+- bot.sannysoft.com — 31 pass / 0 fail
+- CreepJS — Grade A, 0% headless, 0% stealth
+- tls.peet.ws — JA4 matches real Chrome with rotating GREASE
+- browserleaks.com (canvas / webgl / webrtc / javascript) — all pass
+- fingerprint.com/demo — passes
+- pixelscan.net — passes
+- browserscan.net — passes
+
+**Real-target scoreboard:**
+- nowsecure.nl (Cloudflare bot-fight test, nodriver author's public benchmark) — passes without challenge
+- antoinevastel.com/bots (ex-DataDome VP of Research) — loads without block
+- Anthem.com (Okta MFA, Angular SPA, real insurance claim submission) — end-to-end flow successful
+
+---
+
+## Install
+
+```bash
+npm install @rester159/blacktip
+npx patchright install chrome   # install the Chromium backend patchright uses
+```
+
+Or pin to a local checkout during development:
+
+```json
+{
+  "dependencies": {
+    "@rester159/blacktip": "link:../blacktip"
+  }
+}
+```
+
+Run `npm install` once, then any change you make to BlackTip's compiled `dist/` is instantly visible to the consuming app (see *Local development* below).
+
+---
+
+## Quick start
+
+```typescript
+import { BlackTip } from '@rester159/blacktip';
+
+const bt = new BlackTip({
+  logLevel: 'info',
+  timeout: 10_000,
+  retryAttempts: 2,
+  deviceProfile: 'desktop-windows',
+  behaviorProfile: 'human',
+});
+
+await bt.launch();
+await bt.navigate('https://example.com');
+await bt.waitForStable();
+await bt.type('input[name="email"]', 'you@example.com', { paste: true });
+await bt.click('button[type="submit"]');   // importance auto-detected as high
+await bt.waitForText('Welcome');
+await bt.close();
+```
+
+## Agent mode (recommended)
+
+For LLM-driven flows, use the TCP serve mode. Start the server once and send commands to it. Each response is a JSON bundle with the result, current URL, page title, and a base64 screenshot.
+
+```bash
+# Terminal 1: start the server
+npx blacktip serve
+
+# Terminal 2: drive it
+npx blacktip send "await bt.navigate('https://example.com')" --pretty
+npx blacktip send "await bt.clickText('Sign in')" --pretty
+npx blacktip send --file login.js --pretty
+```
+
+MFA handling:
+
+```typescript
+// Inside a command sent to the server:
+const code = await bt.pauseForInput({ prompt: 'Enter SMS code', validate: /^\d{6}$/ });
+await bt.type('input[name="credentials.passcode"]', code, { paste: true });
+```
+
+When BlackTip hits `pauseForInput`, it sends a `{paused:true, pauseId, prompt}` frame to your client and waits. You relay the prompt to the user, get their answer, then resume:
+
+```bash
+npx blacktip resume pause-1712345678-12345 "116170"
+```
+
+See `AGENTS.md` for the full agent-facing reference, including the decision tree for common situations and the list of mistakes to avoid.
+
+---
+
+## Core API
+
+| Method | Purpose |
+|---|---|
+| `bt.launch()` / `bt.close()` | Lifecycle |
+| `bt.navigate(url, opts?)` | Go to URL |
+| `bt.click(selector, opts?)` | Click by CSS/XPath. Auto-dismisses overlays, verifies interactive hit, applies importance hesitation. |
+| `bt.clickText(text, {nth?, exact?, importance?})` | Click by visible text. Auto-detects "Submit"/"Pay"/"Confirm" as high importance. |
+| `bt.clickRole(role, {name?})` | Click by ARIA role |
+| `bt.type(selector, text, {paste?, importance?})` | Type into input. Uses `keyboard.type` for React/Angular compat, falls back to `fill()` if framework didn't register. |
+| `bt.select(selector, value)` | Select `<option>` by value OR label |
+| `bt.scroll({direction, amount})` | Scroll with natural deceleration |
+| `bt.screenshot({path?})` | PNG or JPEG |
+| `bt.waitForStable({networkIdleMs, domIdleMs, maxMs})` | Wait for page to settle — replaces fixed sleeps |
+| `bt.waitForText(text, {timeout})` | Wait for text to appear in body innerText |
+| `bt.waitFor(selector, {timeout, visible?})` | Wait for element |
+| `bt.inspect(selector)` | `{exists, visible, tagName, text, attributes, boundingBox}` in one call |
+| `bt.listOptions(buttonIdOrSelector)` | Enumerate Angular-style custom dropdowns |
+| `bt.networkSince(ms, pattern?)` | Recent network requests filtered by URL pattern |
+| `bt.didRequestFireSince(pattern, ms)` | Boolean: did a matching request fire? |
+| `bt.dismissOverlays()` | Hide fixed/sticky overlays (chat widgets, cookie banners, Medallia, etc.) |
+| `bt.extractText(selector, {multiple?})` | Get innerText |
+| `bt.extractAttribute(selector, attr)` | Get attribute value |
+| `bt.extractTable(selector)` | Parse `<table>` into row objects |
+| `bt.findInShadowDom(cssSelector, {timeout?})` | Pierce open shadow roots |
+| `bt.uploadFile(selector, path)` | File upload |
+| `bt.download(selector, {saveTo})` | Click-to-download with metadata |
+| `bt.frame(selector)` / `bt.frames()` | Iframe context (Stripe Elements, Braintree Hosted Fields) |
+| `bt.getTabs()` / `bt.newTab()` / `bt.switchTab(i)` / `bt.closeTab(i?)` | Tab management |
+| `bt.cookies()` / `bt.setCookies()` / `bt.clearCookies()` | Cookie jar |
+| `bt.executeJS(script)` | Raw JS evaluation |
+| `bt.pauseForInput({prompt, validate?, timeoutMs?})` | User-in-the-loop (MFA) |
+| `bt.serve(port?)` | Start TCP command server |
+
+Plus `SnapshotManager`, `ProxyPool`, `attachObservability`, and the calibration module — see the TypeScript types for details.
+
+---
+
+## Configuration
+
+```typescript
+new BlackTip({
+  logLevel: 'info' | 'debug' | 'warn' | 'error',
+  timeout: 10_000,
+  retryAttempts: 2,
+  deviceProfile: 'desktop-windows' | 'desktop-macos' | 'desktop-linux',
+  behaviorProfile: 'human' | 'scraper' | ProfileConfig,
+  headless: false,  // Always runs headful via channel:'chrome'
+  locale: 'en-US',
+  timezone: 'America/New_York',
+  screenResolution: { width: 1920, height: 1080 },
+  proxy: 'http://user:pass@host:port',
+  chromiumPath: '/custom/chrome',
+});
+```
+
+---
+
+## Local development
+
+If you're iterating on BlackTip alongside a consuming app:
+
+```bash
+# In the BlackTip directory — leave this running
+npm run dev   # alias for tsc --watch
+
+# In the consuming app's package.json
+{
+  "dependencies": {
+    "@rester159/blacktip": "link:../blacktip"
+  }
+}
+
+# Install once
+npm install
+```
+
+Changes to BlackTip's `.ts` files recompile to `dist/` on save, and the consuming app sees them instantly via the symlink.
+
+---
+
+## What BlackTip is NOT
+
+- **Not an agent.** It doesn't plan or decide. A human or an LLM drives it.
+- **Not a headless mode tool.** Always runs headful via real Chrome. There is no `headless: true` path that passes serious detectors.
+- **Not a captcha solver.** It doesn't solve captchas. You can integrate a solver service (2captcha, CapSolver, Anti-Captcha) on top.
+- **Not a scraper framework.** No URL queues, no robots.txt compliance built in, no rate limiting — those are the caller's responsibility.
+- **Not a guarantee.** No stealth tool is. It passes every free detector and matches commercial tools on ~85-90% of checks, but the detection landscape updates constantly.
+
+---
+
+## Acceptable use
+
+BlackTip is dual-use. It is appropriate for:
+
+- **Authorized penetration testing** (under formal scope agreements)
+- **Security research** (browser fingerprinting, anti-bot research, academic work)
+- **Your own accounts** on services whose Terms of Service you have accepted
+- **Legitimate automation** where the site's ToS permits automated access
+- **Defensive work** (bot detection development — running BlackTip against your own site to see what slips through)
+
+It is NOT appropriate for:
+
+- Unauthorized access to any system
+- Circumventing paywalls or subscription limits
+- Scraping sites that explicitly forbid automation in their ToS
+- Fraud, impersonation, or identity-related offenses
+- Harassment or spam automation
+- Any activity that would violate the Computer Fraud and Abuse Act or equivalent laws in your jurisdiction
+
+The authors disclaim responsibility for misuse. If you're unsure whether your use case is legitimate, it probably isn't.
+
+---
+
+## License
+
+MIT. See `LICENSE`.

package/dist/behavioral/calibration.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Behavioral calibration — ingestion and parameter-fitting for real
+ * human mouse dynamics and keystroke dynamics datasets.
+ *
+ * This module is a scaffold. The actual dataset downloads (Balabit Mouse
+ * Dynamics Challenge, Chao Shen's mouse data, CMU Keystroke Dynamics,
+ * GREYC-NISLAB) are not bundled — they're free-for-research but have
+ * varying license terms and live on academic FTP sites that come and go.
+ * The structure here is designed so that when you DO have a dataset in
+ * hand (CSV, JSON, or the dataset's native format), you can write a tiny
+ * parser, feed it through `fitFromSamples`, and get back a
+ * `CalibratedProfile` that plugs directly into `BehavioralEngine`.
+ *
+ * The philosophy is: we don't ship training data, we ship the
+ * calibration pipeline. Users bring their own data, we turn it into a
+ * behavioral profile. This avoids license issues and lets different
+ * users calibrate against different populations (e.g., a bank's fraud
+ * team might calibrate against their own telemetry).
+ */
+import type { ProfileConfig } from '../types.js';
+/** A single mouse-movement observation: one (x, y, t) triple plus the
+ *  source target if known. */
+export interface MouseSample {
+    /** Time in milliseconds since the start of the movement. */
+    timestampMs: number;
+    /** Cursor position at that time. */
+    x: number;
+    y: number;
+    /** Optional: the target center the user was aiming at, if known. */
+    targetX?: number;
+    targetY?: number;
+    /** Optional: width of the target in pixels (needed for Fitts' Law fit). */
+    targetWidth?: number;
+}
+/** A complete movement — cursor samples from the start of motion to the
+ *  click. Many datasets ship this as a sequence. */
+export interface MouseMovement {
+    samples: MouseSample[];
+    /** Did the movement end with a click? Some datasets mix navigation
+     *  moves with target clicks. */
+    endedWithClick: boolean;
+}
+/** A single keystroke observation. */
+export interface KeystrokeSample {
+    /** The key character produced (for layout-aware fitting). */
+    key: string;
+    /** Milliseconds from the previous keystroke's down-event. */
+    flightTimeMs: number;
+    /** Milliseconds the key was held down. */
+    holdTimeMs: number;
+}
+/** A complete typing session — a sequence of keystrokes for a single
+ *  phrase or field. */
+export interface TypingSession {
+    keystrokes: KeystrokeSample[];
+    /** Original text that was typed, if known. */
+    phrase?: string;
+}
+export interface DistributionFit {
+    min: number;
+    max: number;
+    mean: number;
+    sigma: number;
+    p5: number;
+    p50: number;
+    p95: number;
+    sampleCount: number;
+}
+export interface MouseFit {
+    /** Fitts' Law intercept constant a (ms). */
+    fittsA: number;
+    /** Fitts' Law slope constant b (ms per bit of index of difficulty). */
+    fittsB: number;
+    /** Distribution of path length divided by straight-line distance
+     *  (how much the user's path curved). Real humans ~1.05–1.15. */
+    pathCurvatureRatio: DistributionFit;
+    /** Distribution of the maximum perpendicular deviation from the
+     *  straight line, in pixels. */
+    perpendicularDeviation: DistributionFit;
+    /** Distribution of "overshoot and correct" distances in pixels for
+     *  targets smaller than 50px. */
+    overshootPx: DistributionFit;
+}
+export interface TypingFit {
+    /** Overall flight-time distribution across all keystrokes. */
+    flightTime: DistributionFit;
+    /** Hold-time distribution. */
+    holdTime: DistributionFit;
+    /** Digraph-specific flight times for common pairs (th, er, in, etc.). */
+    digraphFlightTime: Record<string, DistributionFit>;
+    /** Mistake rate (typos per character). */
+    mistakeRate: number;
+}
+/**
+ * A calibrated behavioral profile: raw fits plus a `ProfileConfig` that
+ * is derived from them and ready to pass to `new BehavioralEngine(...)`.
+ */
+export interface CalibratedProfile {
+    name: string;
+    source: string;
+    sampleCount: number;
+    mouse: MouseFit;
+    typing: TypingFit;
+    profileConfig: ProfileConfig;
+}
+/**
+ * Fit a `DistributionFit` to a 1D array of observations.
+ * Uses the empirical min/max/mean/stddev and samples the empirical CDF
+ * for the 5/50/95 percentiles rather than assuming normality — many
+ * behavioral measurements are right-skewed (log-normal-ish).
+ */
+export declare function fitDistribution(samples: readonly number[]): DistributionFit;
+/**
+ * Fit Fitts' Law constants (a, b) from a set of mouse movements via
+ * ordinary least squares on (log2(D/W + 1), MT).
+ *
+ * Falls back to the canonical (a=90, b=140) if the dataset doesn't
+ * provide target widths.
+ */
+export declare function fitFittsLaw(movements: readonly MouseMovement[]): {
+    a: number;
+    b: number;
+};
+/**
+ * Fit mouse dynamics from a set of recorded movements.
+ */
+export declare function fitMouseDynamics(movements: readonly MouseMovement[]): MouseFit;
+/**
+ * Fit typing dynamics from a set of recorded typing sessions.
+ */
+export declare function fitTypingDynamics(sessions: readonly TypingSession[]): TypingFit;
+/**
+ * Given fitted mouse and typing dynamics, derive a ProfileConfig that
+ * plugs into `new BehavioralEngine(profileConfig)`.
+ *
+ * The mapping is conservative: we use the 5th–95th percentiles from the
+ * fits as the `[min, max]` tuples for the engine's uniform-ish sampling.
+ */
+export declare function deriveProfileConfig(mouse: MouseFit, typing: TypingFit): ProfileConfig;
+/**
+ * End-to-end calibration: take raw mouse movements and typing sessions,
+ * produce a CalibratedProfile.
+ */
+export declare function fitFromSamples(name: string, source: string, movements: readonly MouseMovement[], sessions: readonly TypingSession[]): CalibratedProfile;
+//# sourceMappingURL=calibration.d.ts.map

package/dist/behavioral/calibration.d.ts.map

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