aetherius 0.2.0__py3-none-any.whl

aetherius/stealth/gestures/library.py

@@ -0,0 +1,126 @@
+"""Gesture library: load, downsample, analyze and match mouse traces by distance and angle.
+
+Source-agnostic on purpose. A *gesture* is a list of ``[dx, dy, t]`` points — offsets from the
+gesture's start (so the last point is its total displacement) and ``t`` the elapsed seconds. Where
+those traces come from is irrelevant here: the bundled seed is synthetic (``meta.source``), the
+gesture recorder will add real human traces, and a future model could generate them — all behind
+this one interface. Matching finds the recorded trace whose shape (distance + direction) is closest
+to a requested move, which the mouse humanizer then transforms geometrically onto the real target.
+
+Generalized from the BioMouse system (see legacy_examples/). Pure stdlib ``math``: no numpy, so the
+whole thing runs in the base test suite.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from random import Random
+from typing import Any
+
+# A single sampled point: horizontal offset, vertical offset, elapsed seconds since the start.
+Point = tuple[float, float, float]
+
+_DATA_FILE = Path(__file__).resolve().parent / "data" / "human_library.json"
+# Direction error is far more visible than distance error, so weight the angle term heavily.
+_ANGLE_WEIGHT = 100.0
+# Bound the linear scan so matching stays O(1) per mouse move regardless of library size.
+_DEFAULT_SAMPLE = 50
+
+
+@dataclass(frozen=True, slots=True)
+class Gesture:
+    """One analyzed trace: its downsampled points plus its overall distance and direction."""
+
+    points: list[Point]
+    distance: float
+    angle: float
+
+
+def _downsample(points: list[Point], min_dist: float = 3.0) -> list[Point]:
+    """Drop points closer than *min_dist* px to the last kept one, preserving the endpoints.
+
+    Thinning near-duplicate samples cuts the number of ``mouse.move`` calls at replay time without
+    changing the perceived trajectory.
+    """
+    if len(points) < 3:
+        return list(points)
+    kept = [points[0]]
+    last_x, last_y = points[0][0], points[0][1]
+    for point in points[1:-1]:
+        if math.hypot(point[0] - last_x, point[1] - last_y) >= min_dist:
+            kept.append(point)
+            last_x, last_y = point[0], point[1]
+    kept.append(points[-1])
+    return kept
+
+
+def _analyze(points: list[Point]) -> Gesture | None:
+    """Downsample a raw trace and compute its displacement vector, or ``None`` if degenerate."""
+    clean = _downsample([(float(x), float(y), float(t)) for x, y, t in points])
+    if len(clean) < 2:
+        return None
+    end_x, end_y, _ = clean[-1]
+    return Gesture(points=clean, distance=math.hypot(end_x, end_y), angle=math.atan2(end_y, end_x))
+
+
+class GestureLibrary:
+    """An analyzed, matchable collection of gestures, independent of where they were recorded."""
+
+    def __init__(self, gestures: list[Gesture], meta: dict[str, Any] | None = None) -> None:
+        self._gestures = gestures
+        self.meta = meta or {}
+
+    @classmethod
+    def from_data(cls, data: dict[str, Any]) -> "GestureLibrary":
+        """Build a library from parsed JSON (``{"meta": {...}, "gestures": [...]}``)."""
+        analyzed = [g for raw in data.get("gestures", []) if (g := _analyze(raw)) is not None]
+        meta = data.get("meta")
+        return cls(analyzed, meta if isinstance(meta, dict) else {})
+
+    @classmethod
+    def load(cls, path: Path) -> "GestureLibrary":
+        """Load from a JSON file; a missing file yields an empty library (graceful degradation)."""
+        if not path.exists():
+            return cls([])
+        with path.open(encoding="utf-8") as handle:
+            return cls.from_data(json.load(handle))
+
+    @property
+    def is_empty(self) -> bool:
+        return not self._gestures
+
+    def __len__(self) -> int:
+        return len(self._gestures)
+
+    def best_match(
+        self, distance: float, angle: float, *, rng: Random, sample_size: int = _DEFAULT_SAMPLE
+    ) -> list[Point] | None:
+        """Return the points of the gesture closest to (*distance*, *angle*), or ``None`` if empty.
+
+        Only a random subsample is scored, so matching cost stays flat as the library grows while
+        still drawing on its full variety across calls.
+        """
+        if not self._gestures:
+            return None
+        candidates = rng.sample(self._gestures, min(len(self._gestures), sample_size))
+        best: Gesture | None = None
+        best_score = math.inf
+        for gesture in candidates:
+            angle_diff = abs(gesture.angle - angle)
+            if angle_diff > math.pi:  # normalize wrap-around to the shorter arc
+                angle_diff = 2 * math.pi - angle_diff
+            score = abs(gesture.distance - distance) + angle_diff * _ANGLE_WEIGHT
+            if score < best_score:
+                best_score = score
+                best = gesture
+        return best.points if best is not None else None
+
+
+@lru_cache(maxsize=1)
+def default_library() -> GestureLibrary:
+    """The bundled gesture library, loaded once. Empty if the packaged data file is absent."""
+    return GestureLibrary.load(_DATA_FILE)

aetherius/stealth/gestures/seed.py

@@ -0,0 +1,97 @@
+"""Deterministic generator for the bundled synthetic gesture seed.
+
+The mouse humanizer replays gestures from a library, but the recorder that captures *real* human
+traces is a later milestone. So the package ships a small seed of algorithmically generated traces
+so ``mouse: gestures`` works — and can be tested against a real browser — from day one. Each trace
+follows a minimum-jerk velocity profile (the textbook model of aimed human reaching), with a slight
+terminal overshoot and perpendicular tremor for realism. Because it is seeded, the output is
+reproducible; because :mod:`.library` is source-agnostic, real recorded or model-generated traces
+drop into the exact same format later (``meta.source`` marks the origin).
+
+Regenerate with ``python -m aetherius.stealth.gestures.seed``. Pure stdlib: no numpy.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+from random import Random
+
+from .library import Point
+
+# Distance/direction grid the seed covers, so best_match always finds a close shape for any move.
+_DISTANCES = (60.0, 120.0, 200.0, 300.0, 450.0, 620.0)
+_DIRECTIONS = 8  # cardinal + diagonal
+
+
+def _min_jerk(tau: float) -> float:
+    """Minimum-jerk position profile in [0, 1]: smooth ease-in then ease-out over normalized time."""
+    return tau**3 * (10.0 - 15.0 * tau + 6.0 * tau**2)
+
+
+def generate_gesture(dx: float, dy: float, *, rng: Random) -> list[Point]:
+    """Generate one trace from the origin to ``(dx, dy)`` as ``[x, y, t]`` offset points.
+
+    Sample count scales with distance (more points for longer moves), duration follows a loose
+    speed–distance law, tremor and a small overshoot are largest mid-flight and vanish at the ends
+    so the trace starts at the origin and lands exactly on the target.
+    """
+    distance = math.hypot(dx, dy)
+    ux, uy = (dx / distance, dy / distance) if distance else (0.0, 0.0)
+    perp_x, perp_y = -uy, ux  # unit vector perpendicular to the direction of travel
+
+    samples = max(12, min(40, int(distance / 8)))
+    duration = 0.18 + distance / 1400.0 + rng.uniform(-0.03, 0.05)
+    tremor = rng.uniform(0.6, 1.8)
+    overshoot = rng.uniform(0.01, 0.035) * distance
+
+    points: list[Point] = []
+    for i in range(samples + 1):
+        tau = i / samples
+        bell = math.sin(math.pi * tau)  # 0 at both ends, 1 at mid-flight
+        progress = _min_jerk(tau)
+        along = progress * distance + (overshoot * bell if tau > 0.6 else 0.0)
+        wobble = tremor * bell * rng.uniform(-1.0, 1.0)
+        x = ux * along + perp_x * wobble
+        y = uy * along + perp_y * wobble
+        t = tau * duration
+        points.append((round(x, 2), round(y, 2), round(t, 4)))
+
+    points[0] = (0.0, 0.0, 0.0)
+    points[-1] = (round(dx, 2), round(dy, 2), points[-1][2])
+    return points
+
+
+def generate_library(*, seed: int = 20240705) -> dict[str, object]:
+    """Build the full seed library dict (``meta`` + ``gestures``), deterministic given *seed*."""
+    rng = Random(seed)
+    gestures: list[list[Point]] = []
+    for distance in _DISTANCES:
+        for k in range(_DIRECTIONS):
+            angle = (2 * math.pi * k / _DIRECTIONS) + rng.uniform(-0.12, 0.12)
+            gestures.append(
+                generate_gesture(distance * math.cos(angle), distance * math.sin(angle), rng=rng)
+            )
+    return {
+        "meta": {
+            "source": "synthetic-seed",
+            "model": "min-jerk+overshoot+tremor",
+            "generator": "aetherius.stealth.gestures.seed",
+            "seed": seed,
+            "note": "Bootstrap seed; the gesture recorder adds real human traces via the same format.",
+        },
+        "gestures": gestures,
+    }
+
+
+def write_seed(path: Path | None = None) -> Path:
+    """Write the seed library to disk (defaults to the packaged data file) and return its path."""
+    target = path or (Path(__file__).resolve().parent / "data" / "human_library.json")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(generate_library(), indent=1), encoding="utf-8")
+    return target
+
+
+if __name__ == "__main__":  # pragma: no cover - manual regeneration entry point
+    print(f"Wrote gesture seed to {write_seed()}")

aetherius/stealth/humanizer/__init__.py

@@ -0,0 +1 @@
+"""Human input humanizer: mouse, keyboard, scroll and timing. No-op when stealth is off."""

aetherius/stealth/humanizer/input.py

@@ -0,0 +1,89 @@
+"""HumanInput: the element-level humanized input facade the browser Acts drive.
+
+One object that turns an active :class:`StealthPolicy` into concrete humanized interactions on a
+Playwright page. It speaks only Playwright primitives — a ``locator``, ``page.keyboard``,
+``page.mouse`` — and never touches selectors or Blueprint params, so the dependency runs one way
+(Acts depend on stealth, not the reverse). Each method degrades per feature: with the mouse
+humanizer off, a click is a plain ``locator.click`` but typing can still be humanized, and so on.
+"""
+
+from __future__ import annotations
+
+from random import Random
+from typing import Any
+
+from ..gestures.library import GestureLibrary
+from ..policy import StealthPolicy
+from .keyboard import human_type
+from .mouse import HumanMouse
+from .scroll import human_scroll
+from .timing import Sleeper, precise_sleep
+
+
+class HumanInput:
+    """Humanized click/hover/fill/type/scroll bound to one page, gated by a :class:`StealthPolicy`."""
+
+    def __init__(
+        self,
+        page: Any,
+        policy: StealthPolicy,
+        *,
+        rng: Random | None = None,
+        sleep: Sleeper = precise_sleep,
+        library: GestureLibrary | None = None,
+    ) -> None:
+        self.page = page
+        self.policy = policy
+        self._rng = rng or Random()
+        self._sleep = sleep
+        # Build the gesture mouse only when it is actually requested; otherwise inputs stay plain.
+        self._mouse = (
+            HumanMouse(page, library, rng=self._rng, sleep=self._sleep)
+            if policy.mouse == "gestures"
+            else None
+        )
+
+    def click(self, locator: Any) -> None:
+        if self._mouse is not None:
+            self._mouse.click(locator)
+        else:
+            locator.click()
+
+    def hover(self, locator: Any) -> None:
+        if self._mouse is not None:
+            self._mouse.move_to_locator(locator)
+        else:
+            locator.hover()
+
+    def fill(self, locator: Any, value: str) -> None:
+        """Focus the field, clear it, then enter *value* (humanized if the keyboard feature is on)."""
+        self._focus(locator)
+        keyboard = self.page.keyboard
+        keyboard.press("Control+a")
+        keyboard.press("Delete")
+        self._enter_text(value)
+
+    def type(self, locator: Any, text: str) -> None:
+        """Focus the field and append *text* without clearing (humanized keyboard when enabled)."""
+        self._focus(locator)
+        self._enter_text(text)
+
+    def scroll_by(self, amount: float) -> None:
+        human_scroll(self.page, amount, rng=self._rng, sleep=self._sleep)
+
+    def park(self) -> None:
+        """Idle the cursor away from controls during a wait (no-op unless the mouse is humanized)."""
+        if self._mouse is not None:
+            self._mouse.park()
+
+    def _focus(self, locator: Any) -> None:
+        if self._mouse is not None:
+            self._mouse.click(locator)
+        else:
+            locator.click()
+
+    def _enter_text(self, text: str) -> None:
+        if self.policy.keyboard == "human":
+            human_type(self.page.keyboard, text, rng=self._rng, sleep=self._sleep)
+        else:
+            self.page.keyboard.type(text)

aetherius/stealth/humanizer/keyboard.py

@@ -0,0 +1,75 @@
+"""Human typing: variable per-session speed, occasional typo-and-correct, per-character delays.
+
+Uniform keystroke timing is an obvious tell. :func:`plan_typing` builds the whole keystroke plan up
+front — a pure function of the text and an ``rng`` — so it is fully unit-tested without a keyboard:
+a per-call base speed (some people type faster than others), a small chance of a typo immediately
+corrected with backspace, longer pauses on spaces (word boundaries) and on special characters that
+need a modifier. :func:`human_type` just plays that plan against a Playwright keyboard.
+"""
+
+from __future__ import annotations
+
+import string
+from dataclasses import dataclass
+from random import Random
+from typing import Any, Literal
+
+from .timing import Sleeper, precise_sleep
+
+# Probability a character is preceded by a wrong keystroke that gets corrected.
+_TYPO_PROB = 0.05
+# Never dip below this: the DOM needs time to register each keystroke.
+_MIN_DELAY_S = 0.05
+_SPECIAL_KEYS = frozenset({"#", "@"})
+_DEFAULT_RNG = Random()
+
+
+@dataclass(frozen=True, slots=True)
+class KeyEvent:
+    """One planned keyboard event: type a character or press a key, then wait ``delay`` seconds."""
+
+    kind: Literal["type", "press"]
+    value: str
+    delay: float
+
+
+def _char_delay(char: str, base_speed: float, rng: Random) -> float:
+    """Delay after typing *char*: base session speed plus per-character adjustments, floored."""
+    delay = base_speed + rng.uniform(-0.04, 0.05)
+    if char == " ":
+        delay += rng.uniform(0.08, 0.15)  # brief pause between words
+    if char in _SPECIAL_KEYS:
+        delay += rng.uniform(0.4, 0.8)  # modifier reach slows these down
+    return max(delay, _MIN_DELAY_S)
+
+
+def plan_typing(
+    text: str, *, rng: Random = _DEFAULT_RNG, typo_prob: float = _TYPO_PROB
+) -> list[KeyEvent]:
+    """Return the ordered keystroke plan for *text*, including typo corrections and per-key delays."""
+    base_speed = rng.uniform(0.08, 0.20)
+    events: list[KeyEvent] = []
+    for char in text:
+        if rng.random() < typo_prob:
+            wrong = rng.choice(string.ascii_lowercase)
+            events.append(KeyEvent("type", wrong, rng.uniform(0.15, 0.4)))
+            events.append(KeyEvent("press", "Backspace", rng.uniform(0.1, 0.2)))
+        events.append(KeyEvent("type", char, _char_delay(char, base_speed, rng)))
+    return events
+
+
+def human_type(
+    keyboard: Any,
+    text: str,
+    *,
+    rng: Random = _DEFAULT_RNG,
+    sleep: Sleeper = precise_sleep,
+    typo_prob: float = _TYPO_PROB,
+) -> None:
+    """Type *text* on a Playwright keyboard following a humanized plan (typos, per-key timing)."""
+    for event in plan_typing(text, rng=rng, typo_prob=typo_prob):
+        if event.kind == "type":
+            keyboard.type(event.value)
+        else:
+            keyboard.press(event.value)
+        sleep(event.delay)

aetherius/stealth/humanizer/mouse.py

@@ -0,0 +1,153 @@
+"""Human mouse motion by geometric gesture replay. Generalizes the BioMouse system.
+
+To reach an arbitrary target, pick the library gesture whose shape (distance + direction) is closest
+to the required move, then transform it — uniform scale onto the target distance, rotation onto the
+target direction — and replay it point by point, preserving the recorded inter-point timing. Result:
+every move traces a genuinely human path rather than a straight synthetic line, and no two moves to
+the same spot are identical.
+
+:func:`plan_replay` is the pure geometric transform (unit-tested without a browser). :class:`HumanMouse`
+tracks the virtual cursor and drives a Playwright mouse; ``rng`` and ``sleep`` are injectable.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from random import Random
+from typing import Any
+
+from ..gestures.library import GestureLibrary, Point, default_library
+from .timing import Sleeper, precise_sleep
+
+# Off-center click band: aiming for the exact center every time is a classic bot heuristic.
+_CLICK_BAND = (0.3, 0.7)
+_DEFAULT_RNG = Random()
+
+
+def _rotate(x: float, y: float, angle: float) -> tuple[float, float]:
+    cos_a, sin_a = math.cos(angle), math.sin(angle)
+    return x * cos_a - y * sin_a, x * sin_a + y * cos_a
+
+
+def plan_replay(
+    gesture: list[Point], start: tuple[float, float], target: tuple[float, float]
+) -> list[tuple[float, float, float]]:
+    """Map *gesture* (offsets from its own origin) onto the ``start -> target`` vector.
+
+    Returns absolute ``(x, y, t)`` points — scaled and rotated so the gesture's endpoint lands on
+    *target*, with a final exact-landing correction — where ``t`` is the recorded elapsed time. An
+    empty list means the move is too small to be worth animating.
+    """
+    (sx, sy), (tx, ty) = start, target
+    target_dist = math.hypot(tx - sx, ty - sy)
+    if target_dist < 1.0:
+        return []
+    target_angle = math.atan2(ty - sy, tx - sx)
+
+    end_x, end_y, _ = gesture[-1]
+    orig_dist = math.hypot(end_x, end_y)
+    orig_angle = math.atan2(end_y, end_x)
+    scale = target_dist / orig_dist if orig_dist > 0 else 1.0
+    rotation = target_angle - orig_angle
+
+    points = []
+    for px, py, pt in gesture:
+        rx, ry = _rotate(px * scale, py * scale, rotation)
+        points.append((sx + rx, sy + ry, pt))
+    points.append((tx, ty, gesture[-1][2]))  # guarantee the cursor lands exactly on target
+    return points
+
+
+def _eased_fallback(
+    start: tuple[float, float], target: tuple[float, float], steps: int = 16
+) -> list[tuple[float, float, float]]:
+    """A gentle eased straight-line path, used only when no gesture library is available."""
+    (sx, sy), (tx, ty) = start, target
+    points = []
+    for i in range(1, steps + 1):
+        t = i / steps
+        eased = 1.0 - (1.0 - t) ** 3
+        points.append((sx + (tx - sx) * eased, sy + (ty - sy) * eased, t * 0.4))
+    return points
+
+
+class HumanMouse:
+    """Drives a Playwright mouse along replayed human gestures, tracking the virtual cursor."""
+
+    def __init__(
+        self,
+        page: Any,
+        library: GestureLibrary | None = None,
+        *,
+        rng: Random = _DEFAULT_RNG,
+        sleep: Sleeper = precise_sleep,
+    ) -> None:
+        self._page = page
+        self._library = library if library is not None else default_library()
+        self._rng = rng
+        self._sleep = sleep
+        # Start at a natural-looking position rather than the (0, 0) corner a fresh page reports.
+        self.x = rng.uniform(400.0, 800.0)
+        self.y = rng.uniform(300.0, 600.0)
+
+    def _plan(self, target: tuple[float, float]) -> list[tuple[float, float, float]]:
+        start = (self.x, self.y)
+        dist = math.hypot(target[0] - self.x, target[1] - self.y)
+        angle = math.atan2(target[1] - self.y, target[0] - self.x)
+        gesture = self._library.best_match(dist, angle, rng=self._rng)
+        if gesture is None:
+            return _eased_fallback(start, target)
+        return plan_replay(gesture, start, target)
+
+    def move_to(self, x: float, y: float) -> None:
+        """Move the cursor to ``(x, y)`` along a replayed gesture, honoring its recorded timing."""
+        points = self._plan((x, y))
+        if not points:
+            return
+        anchor = time.perf_counter()
+        for px, py, pt in points:
+            self._page.mouse.move(px, py)
+            behind = pt - (time.perf_counter() - anchor)
+            if behind > 0:
+                self._sleep(behind)
+        self.x, self.y = x, y
+
+    def move_to_locator(self, locator: Any) -> None:
+        """Move to a random point within the center band of *locator*'s bounding box.
+
+        The element is first brought into the viewport, so its box coordinates are actually on
+        screen and the coordinate-based click lands — the same "scroll to it, then reach for it" a
+        person does. Without this, a click on an off-screen target would silently miss.
+        """
+        locator.scroll_into_view_if_needed()
+        box = locator.bounding_box()
+        if not box:
+            return
+        self.move_to(
+            box["x"] + box["width"] * self._rng.uniform(*_CLICK_BAND),
+            box["y"] + box["height"] * self._rng.uniform(*_CLICK_BAND),
+        )
+
+    def click(self, locator: Any) -> None:
+        """Move to *locator* and click it with randomized reaction and hold timing."""
+        self.move_to_locator(locator)
+        self._sleep(self._rng.uniform(0.05, 0.1))  # reaction time after arrival
+        self._page.mouse.down()
+        self._sleep(self._rng.uniform(0.05, 0.1))  # natural press-hold variance
+        self._page.mouse.up()
+
+    def park(self) -> None:
+        """Idle the cursor near the bottom of the viewport, away from interactive elements.
+
+        A natural resting behaviour during long waits: a real user's cursor drifts off the controls
+        rather than hovering them. Generalizes BioMouse.park_mouse_at_bottom.
+        """
+        size = self._page.evaluate(
+            "() => ({ width: window.innerWidth, height: window.innerHeight })"
+        )
+        width, height = float(size["width"]), float(size["height"])
+        self.move_to(
+            self._rng.uniform(50.0, max(50.0, width - 50.0)),
+            height - self._rng.uniform(20.0, 50.0),
+        )

aetherius/stealth/humanizer/scroll.py

@@ -0,0 +1,55 @@
+"""Human scrolling: a cubic ease-out wheel curve instead of one instantaneous jump.
+
+Real wheel scrolling decelerates — fast at first, easing to a stop — so a single large
+``mouse.wheel`` delta reads as automation. :func:`ease_out_deltas` turns a target distance into a
+sequence of per-frame ``(delta, dt)`` steps following a cubic ease-out; it is pure, so the curve is
+unit-tested without a browser. :func:`human_scroll` simply plays those steps against a page.
+"""
+
+from __future__ import annotations
+
+from random import Random
+from typing import Any, Callable
+
+from .timing import Sleeper, precise_sleep
+
+# ~12 ms per step tracks a 60 fps frame budget, giving visually smooth motion without flooding the
+# input queue with wheel events.
+_STEP_MS = 12.0
+_DEFAULT_RNG = Random()
+
+
+def ease_out_deltas(
+    amount: float, duration_ms: float, step_ms: float = _STEP_MS
+) -> list[tuple[float, float]]:
+    """Break a scroll of *amount* px over *duration_ms* into ``(delta_px, dt_s)`` ease-out steps.
+
+    Cubic ease-out (``1 - (1 - t)^3``) front-loads the movement and settles softly. Per-step deltas
+    are differences of the eased cumulative offset, so they sum exactly to *amount*.
+    """
+    steps = max(1, int(duration_ms / step_ms))
+    dt = step_ms / 1000.0
+    deltas: list[tuple[float, float]] = []
+    last = 0.0
+    for i in range(1, steps + 1):
+        t = i / steps
+        eased = amount * (1.0 - (1.0 - t) ** 3)
+        deltas.append((eased - last, dt))
+        last = eased
+    return deltas
+
+
+def human_scroll(
+    page: Any,
+    amount: float,
+    *,
+    duration_ms: float | None = None,
+    rng: Random = _DEFAULT_RNG,
+    sleep: Sleeper = precise_sleep,
+) -> None:
+    """Scroll the page vertically by *amount* px with an eased, stepped wheel motion."""
+    total_ms = duration_ms if duration_ms is not None else rng.uniform(600.0, 1000.0)
+    wheel: Callable[[float, float], None] = page.mouse.wheel
+    for delta, dt in ease_out_deltas(amount, total_ms):
+        wheel(0.0, delta)
+        sleep(dt)

aetherius/stealth/humanizer/timing.py

@@ -0,0 +1,54 @@
+"""Human timing primitives: precise sleep and random, occasionally distracted pauses.
+
+``time.sleep`` has coarse OS granularity (~10-15 ms), too blunt for the sub-millisecond intervals a
+replayed gesture needs, so :func:`precise_sleep` busy-waits below a 20 ms threshold and defers to
+``time.sleep`` above it. :func:`human_pause` is the "think time" between actions: a random dwell
+that, now and then, stretches into a longer distraction — the kind of irregular rhythm a real user
+produces and a fixed delay never does.
+
+``rng`` and ``sleep`` are injectable so tests stay deterministic and instant.
+"""
+
+from __future__ import annotations
+
+import time
+from random import Random
+from typing import Callable
+
+# Below this, OS sleep granularity dominates, so busy-wait for accuracy; above it, yield the CPU.
+_BUSY_WAIT_THRESHOLD_S = 0.02
+
+Sleeper = Callable[[float], None]
+_DEFAULT_RNG = Random()
+
+
+def precise_sleep(duration: float) -> None:
+    """Sleep *duration* seconds accurately, busy-waiting under 20 ms where ``time.sleep`` is too coarse."""
+    if duration <= 0:
+        return
+    if duration > _BUSY_WAIT_THRESHOLD_S:
+        time.sleep(duration)
+        return
+    end = time.perf_counter() + duration
+    while time.perf_counter() < end:
+        pass
+
+
+def human_pause(
+    min_s: float,
+    max_s: float,
+    distraction: float = 0.0,
+    *,
+    rng: Random = _DEFAULT_RNG,
+    sleep: Sleeper = precise_sleep,
+) -> float:
+    """Sleep a random duration in ``[min_s, max_s]``, occasionally extended by a distraction.
+
+    With probability *distraction* an extra 1.5-4 s is added, mimicking a user glancing away. Returns
+    the total slept, so callers (and tests) can observe the decision without timing the wall clock.
+    """
+    duration = rng.uniform(min_s, max_s)
+    if distraction > 0 and rng.random() < distraction:
+        duration += rng.uniform(1.5, 4.0)
+    sleep(duration)
+    return duration

aetherius/stealth/ml/__init__.py

@@ -0,0 +1 @@
+"""Optional machine-learning upgrades for stealth, behind the same interfaces. Roadmap, not required day one."""

aetherius/stealth/ml/fingerprint_model.py

@@ -0,0 +1 @@
+"""Coherent fingerprint sampling from realistic hardware and browser combinations."""

aetherius/stealth/ml/motion_model.py

@@ -0,0 +1 @@
+"""Generative human-motion model: sample from a distribution of traces instead of a finite recorded library."""