captchakraken 2.8.0 → 3.0.0

package/python/src/captchakraken/selectors.py

@@ -0,0 +1,184 @@
+"""Every selector the driver knows, keyed by vendor. Mirrored in js/src/selectors.ts; keep both in the same order,
+because detection takes the first visible match in table order."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import Mapping, NamedTuple, Optional, Sequence, Tuple
+
+from .kinds import FrameRole, RecaptchaBanner, Vendor
+
+
+@dataclass(frozen=True)
+class VendorSelectors:
+    # URL substrings of the vendor's code on the wire. A tripwire, not a detector: the host stays on the wire when a
+    # vendor renames its markup (see TRIBAL_KNOWLEDGE.md). BotDetect is self-hosted, so it has none.
+    hosts: Sequence[str]
+    # On the host page: the open challenge. Detected first.
+    challenge: Sequence[str] = ()
+    # On the host page: the checkbox. Detected while `response` is empty and `checked` is not showing.
+    checkbox: Sequence[str] = ()
+    # On the host page: inline widget shapes, detected last. Iframe selectors go first; a class that lives inside the
+    # frame document (.CheckboxCaptcha, .mtcap) only ever matches an inline embed.
+    widget: Sequence[str] = ()
+    # On the host page: the field the vendor fills on success. Read first and unconditionally, because hCaptcha's
+    # overlay hides the anchor.
+    response: Optional[str] = None
+    # Inside the checkbox frame: the box shows accepted. Demo pages do not always fill `response`.
+    checked: Optional[str] = None
+    # On the host page: the vendor painted its success state. Visibility is part of the test (see TRIBAL_KNOWLEDGE.md).
+    accepted: Optional[str] = None
+    # Inside the challenge frame: a new round has painted, with text.
+    fresh: Optional[str] = None
+    # Inside the challenge frame: the pictures a board is made of; the driver waits for each to have painted.
+    images: Sequence[str] = ()
+    # Inside the widget: the vendor's own submit control, tried after the generic text probes.
+    submit: Sequence[str] = ()
+    # Inside the challenge frame: verdict banners and what each means.
+    banners: Sequence[Tuple[str, RecaptchaBanner]] = ()
+    # Inside the widget, and its enclosing fieldset/form: the answer box of a typed captcha.
+    text_input: Sequence[str] = ()
+    # Inside the widget: the knob a slide must start on; a drag from the piece moves nothing.
+    slider_handle: Sequence[str] = ()
+    # Inside the widget: the piece, measured to steer the slide and dragged directly when there is no track.
+    piece: Sequence[str] = ()
+
+
+SELECTORS: Mapping[Vendor, VendorSelectors] = {
+    Vendor.RECAPTCHA: VendorSelectors(
+        hosts=("google.com/recaptcha", "recaptcha.net"),
+        challenge=('iframe[src*="recaptcha/api2/bframe"]',),
+        checkbox=('iframe[src*="recaptcha/api2/anchor"]:not([src*="size=invisible"])',),
+        response='[name="g-recaptcha-response"]',
+        checked=".recaptcha-checkbox-checked",
+        fresh=".rc-imageselect-instructions, #rc-imageselect",
+        submit=("#recaptcha-verify-button",),
+        banners=(
+            (".rc-imageselect-error-select-more", RecaptchaBanner.SELECT_MORE),
+            (".rc-imageselect-error-dynamic-more", RecaptchaBanner.DYNAMIC_MORE),
+            (".rc-imageselect-incorrect-response", RecaptchaBanner.REJECTED),
+        ),
+    ),
+    # Keyed on the `hcaptcha` substring, not the apex host: challenges are served off newassets.hcaptcha.com.
+    Vendor.HCAPTCHA: VendorSelectors(
+        hosts=("hcaptcha.com",),
+        challenge=('iframe[src*="hcaptcha"][src*="frame=challenge"]',),
+        checkbox=('iframe[src*="hcaptcha"][src*="frame=checkbox"]',),
+        response='[name="h-captcha-response"]',
+        checked='#checkbox[aria-checked="true"]',
+        fresh=".prompt-text",
+        images=(".task-image .image", ".task .image", ".challenge-example img", ".image-wrapper img"),
+        submit=(".button-submit",),
+    ),
+    Vendor.TURNSTILE: VendorSelectors(
+        hosts=("challenges.cloudflare.com",),
+        checkbox=('iframe[src*="challenges.cloudflare.com"]', ".cf-turnstile"),
+        response='[name="cf-turnstile-response"]',
+    ),
+    Vendor.GEETEST: VendorSelectors(
+        hosts=("geetest.com",),
+        widget=(".geetest_box", ".geetest_panel_box", ".geetest_popup_window", ".geetest_widget"),
+        accepted=(".geetest_result_tips.geetest_success, .geetest_captcha.geetest_success, "
+                  ".geetest_captcha.geetest_lock_success"),
+        submit=(".geetest_submit",),
+        slider_handle=(".geetest_slider_button", ".geetest_btn", ".geetest_slider .geetest_arrow"),
+        piece=(".geetest_slice",),
+    ),
+    # Both in-page and iframe shapes stay (Tencent moved in-host on 2026-08-11; see TRIBAL_KNOWLEDGE.md), and the iframe
+    # id is prefix-anchored: `[id*=tcaptcha]` also matched MTCaptcha's iframe and hid that `.mtcap` matched nothing.
+    Vendor.TENCENT: VendorSelectors(
+        hosts=("captcha.gtimg.com", "captcha.qcloud.com"),
+        widget=("#tcaptcha_transform_dy", "#tCaptchaDyContent", ".tencent-captcha-dy__content", "iframe#tcaptcha_iframe_dy",
+                'iframe[id^="tcaptcha"]', 'iframe[src*="captcha.gtimg.com"]', 'iframe[src*="captcha.qq.com"]'),
+        slider_handle=(".tencent-captcha-dy__slider-block", "#tcaptcha_drag_thumb", ".tc-slider-normal", "[id*=slideBlock]"),
+        piece=(".tencent-captcha-dy__fg-item",),
+    ),
+    Vendor.YIDUN: VendorSelectors(
+        hosts=("dun.163.com", "cstaticdun.126.net", "necaptcha.nosdn.127.net"),
+        widget=(".yidun_panel", ".yidun"),
+        slider_handle=(".yidun_slider", ".yidun_jigsaw"),
+        piece=(".yidun_jigsaw",),
+    ),
+    Vendor.YANDEX: VendorSelectors(
+        hosts=("smartcaptcha.yandexcloud.net",),
+        widget=('iframe[src*="smartcaptcha.yandexcloud.net/advanced"]', 'iframe[src*="smartcaptcha.yandexcloud.net"]',
+                ".CheckboxCaptcha"),
+        text_input=(".AdvancedCaptcha-Input input", "input.Textinput-Control", 'input[name="rep"]'),
+    ),
+    Vendor.LEMIN: VendorSelectors(
+        hosts=("leminnow.com",),
+        widget=("#lemin-cropped-captcha", ".lemin-captcha-popup"),
+        slider_handle=(".lemin-slider-handle", "#lemin-cropped-captcha .slider"),
+        piece=(".lemin-cropped-puzzle-piece", "#lemin-cropped-captcha canvas + canvas"),
+    ),
+    Vendor.PROSOPO: VendorSelectors(
+        hosts=("prosopo.io",),
+        widget=(".prosopo-modalInner", ".procaptcha-checkbox"),
+    ),
+    Vendor.MTCAPTCHA: VendorSelectors(
+        hosts=("mtcaptcha.com",),
+        widget=('iframe[src*="service.mtcaptcha.com"]', 'iframe[id^="mtcaptcha-iframe"]', ".mtcaptcha", ".mtcap"),
+        text_input=("input.mtcap-inputtext", ".mtcap input[type=text]"),
+    ),
+    Vendor.BOTDETECT: VendorSelectors(
+        hosts=(),
+        widget=(".BDC_CaptchaDiv",),
+        text_input=("input[id*=captchaCode]", "input#captchaCode", "input[id*=validateCaptcha]",
+                    ".BDC_CaptchaDiv input[type=text]"),
+    ),
+    Vendor.UNKNOWN: VendorSelectors(hosts=()),
+}
+assert set(SELECTORS) == set(Vendor), "every vendor names its selectors"
+
+VENDORS: Sequence[Tuple[Vendor, VendorSelectors]] = tuple(SELECTORS.items())
+
+
+def _of_every_vendor(key: str) -> Sequence[str]:
+    assert key in {f.name for f in fields(VendorSelectors)}
+    return tuple(s for _, v in VENDORS for s in getattr(v, key))
+
+
+class WidgetProbe(NamedTuple):
+    vendor: Vendor
+    role: FrameRole
+    selector: str
+
+
+# Every host-page selector with what it names, in detection order: open challenges, then checkboxes, then inline widgets.
+WIDGET_PROBES: Sequence[WidgetProbe] = tuple(
+    WidgetProbe(vendor, role, selector)
+    for role, key in ((FrameRole.CHALLENGE, "challenge"), (FrameRole.CHECKBOX, "checkbox"), (FrameRole.UNKNOWN, "widget"))
+    for vendor, s in VENDORS
+    for selector in getattr(s, key))
+
+RESPONSE_SELECTORS: Sequence[str] = tuple(s.response for _, s in VENDORS if s.response)
+ACCEPTED_SELECTORS: Sequence[str] = tuple(s.accepted for _, s in VENDORS if s.accepted)
+
+_LOWER = "translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"
+
+
+def submit_by_text(text: str) -> str:
+    """`.//` keeps the xpath relative so a host-page widget cannot reach the form's own submit."""
+    return f"xpath=.//button[contains({_LOWER}, '{text}')] | .//div[@role=\"button\" and contains({_LOWER}, '{text}')]"
+
+
+# A real Verify/Next/Submit/Skip first; the vendor-named controls are fallbacks.
+SUBMIT_SELECTORS: Sequence[str] = (*map(submit_by_text, ("verify", "next", "submit", "skip")), *_of_every_vendor("submit"))
+
+# Vendor-named first, generic last: the driver takes the first visible match, and a generic selector
+# reached before the vendor's own is how a captcha's answer ends up in a login form's username box.
+TEXT_INPUT_VENDOR_SELECTORS: Sequence[str] = _of_every_vendor("text_input")
+TEXT_INPUT_SELECTORS: Sequence[str] = (
+    *TEXT_INPUT_VENDOR_SELECTORS,
+    'input[name*="captcha" i]', 'input[id*="captcha" i]', 'input[aria-label*="captcha" i]',
+    'input[placeholder*="code" i]', 'input[autocomplete="off"][type=text]',
+    "input[type=text]", "input:not([type])", "input[type=tel]", "textarea",
+)
+# `[draggable=true]` is absent: HTML5 DnD fires dragstart, not pointermove.
+SLIDER_HANDLE_SELECTORS: Sequence[str] = (
+    *_of_every_vendor("slider_handle"),
+    '[role="slider"]', "[aria-valuenow]",
+    '[class*="slider"][class*="btn"]', '[class*="slider"][class*="button"]',
+    '[class*="slide"][class*="handle"]', '[class*="drag"][class*="thumb"]',
+)
+PIECE_SELECTORS: Sequence[str] = (*_of_every_vendor("piece"), '[class*="puzzle"][class*="piece"]', '[class*="jigsaw"]')

package/python/src/captchakraken/server_manager.py

@@ -1,21 +1,3 @@
-"""
-Hands-off local vLLM lifecycle.
-
-The client never has to think about the server. When the configured endpoint is
-LOCAL and nothing is answering, we start `vllm serve` exactly once — guarded by a
-file lock so concurrent first-callers don't double-spawn — wait for it to become
-healthy, and then proceed. When VLLM_BASE_URL points at a REMOTE host, we assume
-the user manages that server and do nothing (so passing your own URL is all it
-takes to opt out of local management entirely).
-
-Public API:
-    ensure_server(base_url=None)  -> called automatically before the first solve
-    start(background=True)        -> `captchakraken server start`
-    run_foreground()              -> `captchakraken server run`  (exec vllm)
-    stop()                        -> `captchakraken server stop`
-    status(base_url=None)         -> dict for `captchakraken server status`
-"""
-
 import os
 import shutil
 import signal
@@ -29,14 +11,11 @@ import requests
 
 from . import config
 
-# One shared state dir for the pidfile, lockfile, server log, and the hosted-API
-# credentials file. Defined in `config` so the path has a single definition.
 STATE_DIR = config.state_dir()
 LOCK_FILE = STATE_DIR / "vllm.lock"
 PID_FILE = STATE_DIR / "vllm.pid"
 LOG_FILE = STATE_DIR / "vllm.log"
 
-# vLLM cold-starts slowly (weights + LoRA + KV cache warmup). Give it room.
 STARTUP_TIMEOUT_S = int(os.getenv("CAPTCHA_KRAKEN_STARTUP_TIMEOUT", "600"))
 
 
@@ -56,7 +35,6 @@ def is_local(base_url: str) -> bool:
 
 
 def is_healthy(base_url: str, timeout: float = 2.0) -> bool:
-    """True once vLLM answers /health. Cheap enough for the hot-path fast check."""
     try:
         r = requests.get(_server_root(base_url) + "/health", timeout=timeout)
         return r.ok
@@ -65,10 +43,7 @@ def is_healthy(base_url: str, timeout: float = 2.0) -> bool:
 
 
 def _vllm_bin() -> "str | None":
-    """Locate the `vllm` executable. Prefer the one next to the CURRENT Python
-    interpreter (the venv the CLI is running in) — the JS driver invokes us via
-    the venv python without the venv's bin on PATH, so `shutil.which` alone would
-    miss it. Fall back to PATH."""
+    """Next to the current interpreter first: the JS driver invokes the venv python without its bin on PATH."""
     sibling = os.path.join(os.path.dirname(sys.executable), "vllm")
     if os.path.exists(sibling) and os.access(sibling, os.X_OK):
         return sibling
@@ -85,21 +60,17 @@ def _read_pid() -> "int | None":
     except (OSError, ValueError):
         return None
     try:
-        os.kill(pid, 0)  # signal 0 == liveness probe
+        os.kill(pid, 0)
         return pid
     except OSError:
         return None
 
 
 def build_serve_command() -> "list[str]":
-    """The `vllm serve …` argv, assembled entirely from config (model-agnostic).
-
-    --enable-tower-connector-lora is REQUIRED: without it vLLM silently drops the
-    vision-tower half of the LoRA and grid accuracy collapses.
-    """
     return [
         _vllm_bin() or "vllm", "serve", config.base_model(),
         "--reasoning-parser", "qwen3",
+        # REQUIRED: without it vLLM silently drops the vision-tower half of the LoRA and grid accuracy collapses.
         "--enable-lora", "--enable-tower-connector-lora",
         "--max-lora-rank", str(config.max_lora_rank()),
         "--max-model-len", str(config.max_model_len()),
@@ -113,9 +84,8 @@ def build_serve_command() -> "list[str]":
 
 def _serve_env() -> dict:
     env = dict(os.environ)
-    # The server's bearer must match what the client sends. api_key() falls back
-    # to "EMPTY"; only forward a real key (leaving vLLM open when none is set).
     key = config.api_key()
+    # Only forward a real key; api_key() falls back to "EMPTY", which would lock vLLM to a placeholder.
     if key and key != "EMPTY":
         env["VLLM_API_KEY"] = key
     return env
@@ -134,8 +104,6 @@ def _spawn() -> subprocess.Popen:
     logf = open(LOG_FILE, "ab", buffering=0)
     logf.write(f"\n=== captchakraken starting vLLM at {time.strftime('%Y-%m-%dT%H:%M:%S')} ===\n"
                .encode())
-    # Detach into its own process group so it survives the caller and a later
-    # `server stop` can signal the whole group.
     proc = subprocess.Popen(
         cmd,
         stdout=logf,
@@ -153,7 +121,6 @@ def _wait_healthy(base_url: str, timeout: float) -> bool:
     while time.time() < deadline:
         if is_healthy(base_url, timeout=2.0):
             return True
-        # If the child died, stop waiting and surface the log.
         pid = _read_pid()
         if pid is None:
             return False
@@ -162,22 +129,10 @@ def _wait_healthy(base_url: str, timeout: float) -> bool:
 
 
 def ensure_server(base_url: "str | None" = None) -> None:
-    """Guarantee an endpoint is reachable before the first request.
-
-    Fast path: one /health GET when the server is already up. Otherwise, for a
-    LOCAL endpoint with autostart enabled, start vLLM once (lock-guarded) and
-    block until healthy. For a REMOTE endpoint we never spawn — the user owns it.
-    """
     base_url = base_url or config.base_url()
 
-    # REMOTE FIRST. There is nothing to ensure about a server we do not manage,
-    # so asking it for /health before deciding that is a round trip spent to
-    # reach a `return` — and up to `timeout=2.0` of it against a hosted gateway
-    # that serves no /health at all. Paid once per ActionPlanner, which for a
-    # caller using `solve_captcha_on_page` is once per solve.
+    # Remote first: /health against a hosted gateway that serves none costs up to 2s, once per ActionPlanner.
     if not is_local(base_url):
-        # Let the actual request raise a clear connection error rather than
-        # silently trying to boot vLLM locally.
         return
     if is_healthy(base_url):
         return
@@ -185,11 +140,9 @@ def ensure_server(base_url: "str | None" = None) -> None:
         return
 
     STATE_DIR.mkdir(parents=True, exist_ok=True)
-    # File lock so two solves racing on first-use don't both spawn a server.
+    # Two solves racing on first use must not both spawn a server; re-check under the lock.
     lock = _FileLock(LOCK_FILE)
     with lock:
-        # Re-check under the lock: another process may have started it while we
-        # queued, or a previous spawn may still be warming up.
         if is_healthy(base_url):
             return
         if _read_pid() is None:
@@ -201,13 +154,12 @@ def ensure_server(base_url: "str | None" = None) -> None:
             )
 
 
-# ── CLI-facing lifecycle helpers ────────────────────────────────────────────
 def start(background: bool = True) -> dict:
     base_url = config.base_url()
     if is_healthy(base_url):
         return {"status": "already-running", "base_url": base_url, "pid": _read_pid()}
     if not background:
-        run_foreground()  # never returns
+        run_foreground()
     _spawn()
     ok = _wait_healthy(base_url, STARTUP_TIMEOUT_S)
     return {
@@ -219,7 +171,6 @@ def start(background: bool = True) -> dict:
 
 
 def run_foreground() -> None:
-    """Exec `vllm serve` in the foreground (replaces this process)."""
     if not _vllm_available():
         raise RuntimeError(
             "vLLM is not installed. Run ./setup.sh or "
@@ -266,8 +217,6 @@ def status(base_url: "str | None" = None) -> dict:
 
 
 class _FileLock:
-    """Minimal POSIX advisory lock (fcntl). vLLM is Linux-only, so this suffices;
-    on platforms without fcntl it degrades to a best-effort no-op."""
 
     def __init__(self, path: Path):
         self.path = path