@rester159/blacktip 0.1.0

package/dist/behavioral/calibration.js

@@ -0,0 +1,242 @@
+/**
+ * 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).
+ */
+// ── Distribution fitting ──
+/**
+ * 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 function fitDistribution(samples) {
+    if (samples.length === 0) {
+        throw new Error('Cannot fit distribution: empty sample set');
+    }
+    const sorted = [...samples].sort((a, b) => a - b);
+    const n = sorted.length;
+    const min = sorted[0];
+    const max = sorted[n - 1];
+    const mean = sorted.reduce((s, v) => s + v, 0) / n;
+    const variance = sorted.reduce((s, v) => s + (v - mean) ** 2, 0) / n;
+    const sigma = Math.sqrt(variance);
+    const pct = (p) => {
+        const idx = Math.max(0, Math.min(n - 1, Math.floor(p * n)));
+        return sorted[idx];
+    };
+    return {
+        min,
+        max,
+        mean,
+        sigma,
+        p5: pct(0.05),
+        p50: pct(0.5),
+        p95: pct(0.95),
+        sampleCount: n,
+    };
+}
+// ── Mouse fitting ──
+/**
+ * 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 function fitFittsLaw(movements) {
+    const points = [];
+    for (const m of movements) {
+        if (m.samples.length < 2)
+            continue;
+        const first = m.samples[0];
+        const last = m.samples[m.samples.length - 1];
+        const mt = last.timestampMs - first.timestampMs;
+        if (mt <= 0)
+            continue;
+        // Require target info for this sample to contribute.
+        if (last.targetX == null || last.targetY == null || last.targetWidth == null || last.targetWidth <= 0)
+            continue;
+        const d = Math.hypot(last.targetX - first.x, last.targetY - first.y);
+        if (d <= 0)
+            continue;
+        const id = Math.log2(d / last.targetWidth + 1);
+        points.push({ x: id, y: mt });
+    }
+    if (points.length < 5) {
+        // Not enough data — return canonical desktop-mouse values.
+        return { a: 90, b: 140 };
+    }
+    // OLS fit: y = a + b*x
+    const n = points.length;
+    const sumX = points.reduce((s, p) => s + p.x, 0);
+    const sumY = points.reduce((s, p) => s + p.y, 0);
+    const sumXY = points.reduce((s, p) => s + p.x * p.y, 0);
+    const sumX2 = points.reduce((s, p) => s + p.x * p.x, 0);
+    const meanX = sumX / n;
+    const meanY = sumY / n;
+    const b = (sumXY - n * meanX * meanY) / (sumX2 - n * meanX * meanX);
+    const a = meanY - b * meanX;
+    return { a, b };
+}
+/**
+ * Compute path curvature (observed path length / straight-line distance)
+ * and max perpendicular deviation for a single movement.
+ */
+function mouseMovementGeometry(m) {
+    const samples = m.samples;
+    if (samples.length < 2)
+        return null;
+    const start = samples[0];
+    const end = samples[samples.length - 1];
+    const straightDist = Math.hypot(end.x - start.x, end.y - start.y);
+    if (straightDist <= 0)
+        return null;
+    let pathLen = 0;
+    for (let i = 1; i < samples.length; i++) {
+        pathLen += Math.hypot(samples[i].x - samples[i - 1].x, samples[i].y - samples[i - 1].y);
+    }
+    // Perpendicular distance from each sample to the straight start→end line.
+    let maxPerp = 0;
+    const lineDX = end.x - start.x;
+    const lineDY = end.y - start.y;
+    const lineLen = Math.hypot(lineDX, lineDY);
+    for (const s of samples) {
+        const perp = Math.abs((s.x - start.x) * lineDY - (s.y - start.y) * lineDX) / lineLen;
+        if (perp > maxPerp)
+            maxPerp = perp;
+    }
+    return { curvature: pathLen / straightDist, maxPerpDeviation: maxPerp };
+}
+/**
+ * Fit mouse dynamics from a set of recorded movements.
+ */
+export function fitMouseDynamics(movements) {
+    const curvatures = [];
+    const perpDeviations = [];
+    const overshoots = [];
+    for (const m of movements) {
+        const geo = mouseMovementGeometry(m);
+        if (!geo)
+            continue;
+        curvatures.push(geo.curvature);
+        perpDeviations.push(geo.maxPerpDeviation);
+    }
+    const { a: fittsA, b: fittsB } = fitFittsLaw(movements);
+    // Overshoot detection requires knowing which samples are past the
+    // target center. Skip for now — plug in once a dataset with target
+    // labeling is available.
+    const overshootFit = overshoots.length >= 5
+        ? fitDistribution(overshoots)
+        : fitDistribution([5, 8, 10, 12, 15]); // canonical fallback
+    return {
+        fittsA,
+        fittsB,
+        pathCurvatureRatio: curvatures.length >= 5
+            ? fitDistribution(curvatures)
+            : fitDistribution([1.05, 1.08, 1.10, 1.12, 1.15]),
+        perpendicularDeviation: perpDeviations.length >= 5
+            ? fitDistribution(perpDeviations)
+            : fitDistribution([10, 15, 20, 25, 30]),
+        overshootPx: overshootFit,
+    };
+}
+// ── Typing fitting ──
+/**
+ * Fit typing dynamics from a set of recorded typing sessions.
+ */
+export function fitTypingDynamics(sessions) {
+    const allFlights = [];
+    const allHolds = [];
+    const digraphBuckets = new Map();
+    let total = 0;
+    let typos = 0;
+    for (const session of sessions) {
+        for (let i = 0; i < session.keystrokes.length; i++) {
+            const ks = session.keystrokes[i];
+            allFlights.push(ks.flightTimeMs);
+            allHolds.push(ks.holdTimeMs);
+            total++;
+            // Record digraph if we have the previous character too.
+            if (i > 0) {
+                const prev = session.keystrokes[i - 1];
+                const digraph = (prev.key + ks.key).toLowerCase();
+                if (/^[a-z]{2}$/.test(digraph)) {
+                    const list = digraphBuckets.get(digraph) ?? [];
+                    list.push(ks.flightTimeMs);
+                    digraphBuckets.set(digraph, list);
+                }
+            }
+            // A "typo" in this context is a key that was followed by a
+            // backspace within the next 2 keystrokes (if the dataset tracks
+            // that). Simple proxy: assume 2% mistake rate when we can't tell.
+            if (ks.key === 'Backspace')
+                typos++;
+        }
+    }
+    const digraphFit = {};
+    for (const [digraph, samples] of digraphBuckets) {
+        if (samples.length >= 5) {
+            digraphFit[digraph] = fitDistribution(samples);
+        }
+    }
+    return {
+        flightTime: allFlights.length >= 5 ? fitDistribution(allFlights) : fitDistribution([80, 100, 120, 150, 200]),
+        holdTime: allHolds.length >= 5 ? fitDistribution(allHolds) : fitDistribution([40, 60, 80, 100]),
+        digraphFlightTime: digraphFit,
+        mistakeRate: total > 0 ? typos / total : 0.02,
+    };
+}
+// ── Full profile derivation ──
+/**
+ * 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 function deriveProfileConfig(mouse, typing) {
+    return {
+        typingSpeedMs: [Math.round(typing.flightTime.p5), Math.round(typing.flightTime.p95)],
+        pauseBetweenActionsMs: [300, 1000],
+        scrollSpeedMs: [150, 300],
+        mouseMovementCurve: 'bezier',
+        clickDwellMs: [Math.round(typing.holdTime.p5), Math.round(typing.holdTime.p95)],
+        readingWpm: [200, 300],
+        mistakeRate: Math.max(0.001, Math.min(0.1, typing.mistakeRate)),
+        recoveryBehavior: 'natural',
+        pasteThreshold: 50,
+    };
+}
+/**
+ * End-to-end calibration: take raw mouse movements and typing sessions,
+ * produce a CalibratedProfile.
+ */
+export function fitFromSamples(name, source, movements, sessions) {
+    const mouse = fitMouseDynamics(movements);
+    const typing = fitTypingDynamics(sessions);
+    const profileConfig = deriveProfileConfig(mouse, typing);
+    return {
+        name,
+        source,
+        sampleCount: movements.length + sessions.length,
+        mouse,
+        typing,
+        profileConfig,
+    };
+}
+//# sourceMappingURL=calibration.js.map

package/dist/behavioral/calibration.js.map

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

package/dist/behavioral-engine.d.ts

@@ -0,0 +1,156 @@
+import type { ProfileConfig, Point, BoundingBox } from './types';
+/**
+ * Importance level for an action. Drives how long the pre-action hesitation
+ * is (humans hesitate more on consequential actions) and how careful the
+ * mouse path is (more overshoot correction for high-importance targets).
+ */
+export type ActionImportance = 'low' | 'normal' | 'high';
+export interface MouseStep {
+    x: number;
+    y: number;
+    delay: number;
+}
+export interface KeystrokeStep {
+    key: string;
+    delay: number;
+    holdDuration: number;
+    isTypo?: boolean;
+    correctionSequence?: {
+        key: string;
+        delay: number;
+        holdDuration: number;
+    }[];
+}
+export interface ScrollStep {
+    deltaY: number;
+    delay: number;
+}
+export declare const HUMAN_PROFILE: ProfileConfig;
+export declare const SCRAPER_PROFILE: ProfileConfig;
+/**
+ * Box-Muller transform: generates a normally-distributed random number
+ * centered on (min+max)/2 with sigma = (max-min)/6, clamped to [min, max].
+ *
+ * The 6-sigma span means ~99.7% of raw samples already fall within bounds;
+ * clamping handles the remaining tail.
+ */
+export declare function sampleNormal(min: number, max: number): number;
+export declare class BehavioralEngine {
+    private readonly profile;
+    constructor(profile: ProfileConfig);
+    /**
+     * Generate a cubic Bézier mouse path from `from` to `to`.
+     *
+     * - Two random control points are offset perpendicular to the straight line.
+     * - Step count scales with distance (20-50 steps).
+     * - Timing uses an ease-in/ease-out curve (accelerate then decelerate).
+     * - Micro-jitter (±1-3px) simulates hand tremor.
+     * - For distances < 50px to target the path overshoots by 5-15px, then
+     *   curves back, simulating the corrective saccade real users perform.
+     */
+    generateMousePath(from: Point, to: Point): MouseStep[];
+    /**
+     * Generate a realistic keystroke sequence for the given text.
+     *
+     * Cadence rules:
+     *  - Common digraphs  → 60-80% of base delay (muscle-memory pairs)
+     *  - Uncommon symbols  → 130-170% of base delay (hunt-and-peck)
+     *  - Numeric digits    → 110-130% of base delay
+     *  - Everything else   → 100% of base delay (with normal-distribution jitter)
+     *
+     * Typos are injected at the configured `mistakeRate`. Each typo produces:
+     *   wrong char → pause (200-500ms) → backspace → correct char
+     *
+     * Hold duration for every key is 40-100ms, normally distributed.
+     */
+    generateTypingSequence(text: string): KeystrokeStep[];
+    /**
+     * Pre-action pause: sampled from the profile's `pauseBetweenActionsMs` range
+     * using a normal distribution so most pauses cluster around the middle.
+     *
+     * If `importance` is provided, the pause is scaled:
+     *   - 'low'    → 0.5× (skim/browse actions)
+     *   - 'normal' → 1.0× (default)
+     *   - 'high'   → 2.0–3.0× + a hesitation spike for consequential actions
+     *
+     * The rationale: real humans don't hesitate uniformly. They take longer
+     * before clicking "Submit Payment" than before scrolling. Behavioral
+     * biometrics systems profile this correlation — if every click has the
+     * same pre-pause distribution regardless of target importance, that's
+     * itself a bot signal.
+     */
+    generatePreActionPause(importance?: ActionImportance): number;
+    /**
+     * Post-action pause: shorter than pre-action (100-400ms).
+     */
+    generatePostActionPause(): number;
+    /**
+     * Fitts' Law-based movement time estimate for a pointing motion from
+     * the current mouse position to a target of width W at distance D.
+     *
+     * MT = a + b * log2(D / W + 1)
+     *
+     * Where a and b are device-specific constants. For mouse on desktop:
+     *   a ≈ 90 ms  (starting latency)
+     *   b ≈ 140 ms (slope of the speed-accuracy tradeoff)
+     *
+     * These constants are from Card, English & Burr (1978) and have been
+     * reconfirmed many times for general mouse use. Fitts' Law is the best-
+     * validated model of human motor control for pointing tasks and is
+     * exactly what behavioral biometric systems calibrate against. Using
+     * it here means our mouse timings match the distribution real users
+     * produce.
+     *
+     * Returns an estimated movement time in milliseconds, clamped to a
+     * reasonable range so tiny/huge moves don't produce absurd values.
+     */
+    fittsLawMovementTime(distancePx: number, targetWidthPx: number): number;
+    /**
+     * Estimate how long it would take a human to read a given piece of text,
+     * based on the profile's WPM range and an average word length of ~5
+     * characters. Used for "reading pause" simulation before clicking a
+     * button that follows a block of text the user would plausibly scan
+     * (terms of service, error messages, important notices).
+     */
+    generateReadingPause(textLength: number): number;
+    /**
+     * Generate a mouse path that scans left-to-right across a text block
+     * like an eye tracker follows reading gaze. Used before clicking a
+     * button that follows important copy.
+     *
+     * Returns a series of mouse positions sweeping across each line of
+     * the text block, with short dwells at the end of each line (like
+     * a saccade back to the start of the next line).
+     */
+    generateReadingScanPath(textBox: BoundingBox, lineCount: number): MouseStep[];
+    /**
+     * Click dwell: time the button is held down, sampled from profile range.
+     */
+    generateClickDwell(): number;
+    /**
+     * Break a total scroll amount into 3-8 steps with deceleration:
+     * larger deltas first, tapering off toward the end (mimicking a
+     * flick-then-settle scroll gesture).
+     *
+     * Delay between steps is 30-100ms, sampled from the profile's scroll speed.
+     */
+    generateScrollSteps(amount: number, direction: 'up' | 'down'): ScrollStep[];
+    /**
+     * Should the engine paste rather than type? True when text length exceeds
+     * the profile's paste threshold.
+     */
+    shouldPaste(text: string): boolean;
+    /**
+     * Pick a click position inside `box`, biased toward the center via a
+     * normal distribution (sigma = dimension/6). A minimum ±2px offset from
+     * the exact center prevents pixel-perfect robotic clicks.
+     */
+    generateClickPosition(box: BoundingBox): Point;
+    /**
+     * Pick a plausible "wrong" key for a given character by looking at
+     * QWERTY adjacency. Falls back to a random alpha character if the
+     * target isn't in the adjacency map.
+     */
+    private pickAdjacentKey;
+}
+//# sourceMappingURL=behavioral-engine.d.ts.map

package/dist/behavioral-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavioral-engine.d.ts","sourceRoot":"","sources":["../src/behavioral-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAIjE;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kBAAkB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7E;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAID,eAAO,MAAM,aAAa,EAAE,aAU3B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,aAU7B,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAc7D;AAuDD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAE5B,OAAO,EAAE,aAAa;IAQlC;;;;;;;;;OASG;IACH,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,GAAG,SAAS,EAAE;IA2GtD;;;;;;;;;;;;;OAaG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE;IAiErD;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,CAAC,UAAU,GAAE,gBAA2B,GAAG,MAAM;IAsBvE;;OAEG;IACH,uBAAuB,IAAI,MAAM;IAIjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IASvE;;;;;;OAMG;IACH,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAahD;;;;;;;;OAQG;IACH,uBAAuB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE;IAoC7E;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAS5B;;;;;;OAMG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,UAAU,EAAE;IAmC3E;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQlC;;;;OAIG;IACH,qBAAqB,CAAC,GAAG,EAAE,WAAW,GAAG,KAAK;IAiC9C;;;;OAIG;IACH,OAAO,CAAC,eAAe;CAgDxB"}