ricibrowser 0.2.1__py3-none-any.whl

ricibrowser/__init__.py

@@ -0,0 +1,38 @@
+"""ricibrowser — a lightweight two-engine browser automation module.
+
+No Playwright, no Puppeteer, no selenium. Built entirely on the public Chrome
+DevTools Protocol specification (chromedevtools.github.io/devtools-protocol/).
+
+Two engines:
+  - **Lightpanda** (fast path): Zig-based headless engine, CDP at ws://127.0.0.1:9222.
+    For crawl/recon/endpoint discovery — ~16× less memory, ~9× faster than Chromium.
+  - **CDP-Chrome** (thorough path): custom CDP client driving the user's real
+    installed Chrome. For DAST/JS-heavy targets/auth flow testing/anti-bot.
+
+Extensions:
+  - **fingerprint**: Canvas/WebGL/audio fingerprint randomization (opt-in).
+  - **geolocation**: Timezone/locale/geolocation override + proxy rotation pool.
+  - **captcha**: CAPTCHA detection, Cloudflare auto-resolve, solver hooks.
+  - **input**: Human-like mouse movement simulation (bezier curves + timing).
+  - **headers**: Sec-CH-UA consistency + request header ordering.
+
+Usage::
+
+    from ricibrowser import Engine, EngineConfig, EngineType
+
+    engine = Engine(EngineConfig(fast_engine=EngineType.AUTO))
+    page = await engine.fast_browse("https://example.com")
+    print(page.title, page.text[:200])
+
+    session = await engine.create_session()
+    await session.navigate("https://example.com")
+    result = await session.evaluate("document.title")
+    await session.close()
+"""
+
+from ricibrowser.config import EngineConfig, EngineType
+from ricibrowser.engine import Engine
+from ricibrowser.session import Page, Session
+
+__version__ = "0.2.0"
+__all__ = ["Engine", "EngineConfig", "EngineType", "Page", "Session"]

ricibrowser/captcha.py

@@ -0,0 +1,395 @@
+"""CAPTCHA detection, Cloudflare auto-resolve, and solver hook framework.
+
+Detection: identifies which CAPTCHA/anti-bot system is blocking navigation
+(Cloudflare JS challenge, Cloudflare Turnstile, reCAPTCHA v2/v3, hCaptcha).
+
+Auto-resolve: for Cloudflare JS challenges ("Just a moment..."), waits for
+the challenge to auto-resolve in real Chrome (the JavaScript runs natively
+and often passes within 5-10 seconds). Captures the ``cf_clearance`` cookie
+for persistence.
+
+Solver hooks: for CAPTCHAs that can't be auto-resolved (Turnstile,
+reCAPTCHA, hCaptcha), provides a hook interface for external solver services.
+The operator registers a ``CaptchaSolver`` implementation and ricibrowser
+calls it when a CAPTCHA is detected.
+
+Usage::
+
+    from ricibrowser.captcha import CaptCHAHandler, CloudflareAutoSolver
+
+    handler = CaptchaHandler(auto_solver=CloudflareAutoSolver())
+    result = await handler.detect_and_solve(session)
+    if result.solved:
+        print("Challenge resolved!")  # cf_clearance now in cookie jar
+    elif result.captcha_type:
+        print(f"Unsupported: {result.captcha_type} — needs external solver")
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Protocol, runtime_checkable
+
+from ricibrowser.cdp_client import CDPClient, CDPError
+
+logger = logging.getLogger(__name__)
+
+
+class CaptchaType(Enum):
+    """Detected CAPTCHA / anti-bot challenge type."""
+
+    NONE = "none"
+    """No CAPTCHA detected."""
+
+    CLOUDFLARE_JS = "cloudflare_js"
+    """Cloudflare JS challenge ("Just a moment..."). Often auto-resolves."""
+
+    CLOUDFLARE_TURNSTILE = "cloudflare_turnstile"
+    """Cloudflare Turnstile widget. Needs external solver."""
+
+    RECAPTCHA_V2 = "recaptcha_v2"
+    """Google reCAPTCHA v2 (checkbox or invisible). Needs external solver."""
+
+    RECAPTCHA_V3 = "recaptcha_v3"
+    """Google reCAPTCHA v3 (score-based, invisible). Needs external solver."""
+
+    HCAPTCHA = "hcaptcha"
+    """hCaptcha widget. Needs external solver."""
+
+    GENERIC = "generic"
+    """Unknown anti-bot challenge."""
+
+
+@dataclass
+class CaptchaResult:
+    """Result of a CAPTCHA detection / solve attempt."""
+
+    captcha_type: CaptchaType
+    solved: bool
+    cookie_name: str | None = None
+    """The cookie that proves the challenge was solved (e.g. cf_clearance)."""
+    solver_used: str | None = None
+    """Which solver was used (e.g. 'cloudflare_auto', 'external')."""
+    error: str | None = None
+    duration_seconds: float = 0.0
+
+
+@runtime_checkable
+class CaptchaSolver(Protocol):
+    """Protocol for external CAPTCHA solver implementations.
+
+    Operators implement this to integrate third-party solver services
+    (2captcha, anti-captcha, capsolver, etc.) for CAPTCHAs that can't
+    be auto-resolved.
+
+    Example implementation::
+
+        class TwoCaptchaSolver:
+            async def solve(self, captcha_type, site_key, url):
+                # Call the 2captcha API
+                token = await call_service(site_key, url)
+                return CaptchaToken(token=token)
+
+        handler = CaptCHAHandler(solver=TwoCaptchaSolver())
+    """
+
+    async def solve(
+        self,
+        captcha_type: CaptchaType,
+        site_key: str | None,
+        url: str,
+    ) -> str | None:
+        """Solve a CAPTCHA and return the token.
+
+        Args:
+            captcha_type: The type of CAPTCHA detected.
+            site_key: The site key (for reCAPTCHA/hCaptcha/Turnstile).
+            url: The page URL where the CAPTCHA appears.
+
+        Returns:
+            The solver token, or None if the solver can't handle this type.
+        """
+        ...
+
+
+@dataclass
+class CaptchaToken:
+    """A solved CAPTCHA token."""
+    token: str
+    captcha_type: CaptchaType
+
+
+# ── Detection ──────────────────────────────────────────────────────────
+
+
+async def detect_captcha(session) -> CaptchaType:
+    """Detect what type of CAPTCHA or anti-bot challenge is on the current page.
+
+    Checks the DOM for known CAPTCHA widget signatures and the page text
+    for challenge messages.
+    """
+    # Check for Cloudflare JS challenge ("Just a moment...")
+    title = await session.evaluate("document.title") or ""
+    body_text = await session.evaluate(
+        "document.body ? document.body.innerText.substring(0, 500) : ''"
+    ) or ""
+
+    title_lower = title.lower()
+    text_lower = (body_text or "").lower()
+
+    if any(p in title_lower or p in text_lower for p in(
+        "just a moment", "checking your browser", "attention required",
+        "cf-challenge", "challenge-platform",
+    )):
+        return CaptchaType.CLOUDFLARE_JS
+
+    # Check for Cloudflare Turnstile widget
+    turnstile = await session.evaluate_bool(
+        "document.querySelector('.cf-turnstile, [data-sitekey]') !== null"
+    )
+    if turnstile:
+        # Verify it's actually a Turnstile widget (not reCAPTCHA)
+        is_turnstile = await session.evaluate_bool(
+            "document.querySelector('script[src*=\"challenges.cloudflare.com/turnstile\"]') !== null"
+        )
+        if is_turnstile:
+            return CaptchaType.CLOUDFLARE_TURNSTILE
+
+    # Check for reCAPTCHA
+    recaptcha = await session.evaluate_bool(
+        "document.querySelector('.g-recaptcha, [data-sitekey], "
+        "iframe[src*=\"recaptcha\"]') !== null"
+    )
+    if recaptcha:
+        # Check if it's v2 (visible checkbox) or v3 (invisible)
+        visible = await session.evaluate_bool(
+            "document.querySelector('.g-recaptcha') && "
+            "getComputedStyle(document.querySelector('.g-recaptcha')).display !== 'none'"
+        )
+        if visible:
+            return CaptchaType.RECAPTCHA_V2
+        return CaptchaType.RECAPTCHA_V3
+
+    # Check for hCaptcha
+    hcaptcha = await session.evaluate_bool(
+        "document.querySelector('.h-captcha, iframe[src*=\"hcaptcha\"]') !== null"
+    )
+    if hcaptcha:
+        return CaptchaType.HCAPTCHA
+
+    # Generic anti-bot check
+    if any(p in text_lower for p in(
+        "enable javascript and cookies", "please complete the security check",
+        "verify you are human", "are you a robot",
+    )):
+        return CaptchaType.GENERIC
+
+    return CaptchaType.NONE
+
+
+# ── Cloudflare Auto-Solver ────────────────────────────────────────────
+
+
+class CloudflareAutoSolver:
+    """Auto-resolves Cloudflare JS challenges by waiting for native JS execution.
+
+    Cloudflare's "Just a moment..." challenge runs JavaScript that computes
+    a token and auto-submits a form. In a real Chrome browser with real V8
+    engine (which ricibrowser uses), this JavaScript executes natively and
+    the challenge resolves automatically — usually within 5-10 seconds.
+
+    This solver:
+      1. Waits for the challenge page to load
+      2. Polls every 1s for the challenge to clear (body text changes,
+         challenge elements disappear, content loads)
+      3. Checks for the ``cf_clearance`` cookie which proves the challenge passed
+      4. Returns the result with the cookie name
+
+    Limitations:
+      - Only works with real Chrome (not Lightpanda — Lightpanda's V8 may
+        not handle the obfuscated CF JS)
+      - Doesn't work if the CF challenge requires a Turnstile click
+      - If the IP address or User-Agent is too suspicious, CF may loop forever
+    """
+
+    def __init__(self, max_wait: float = 15.0, poll_interval: float = 1.0):
+        self.max_wait = max_wait
+        self.poll_interval = poll_interval
+
+    async def solve(self, session) -> CaptchaResult:
+        """Wait for the Cloudflare JS challenge to auto-resolve.
+
+        Args:
+            session: A ricibrowser Session on the challenge page.
+
+        Returns:
+            CaptchaResult with solved=True if the challenge cleared.
+        """
+        start = time.monotonic()
+
+        for _ in range(int(self.max_wait / self.poll_interval)):
+            elapsed = time.monotonic() - start
+
+            # Check if the challenge has cleared
+            body_text = await session.evaluate(
+                "document.body ? document.body.innerText.substring(0, 200) : ''"
+            )
+
+            # If evaluate returned None (context not ready, CDP error),
+            # treat as "unknown — keep waiting" rather than "cleared".
+            if body_text is None:
+                await asyncio.sleep(self.poll_interval)
+                continue
+
+            text_lower = body_text.lower()
+
+            # Challenge cleared if the "Just a moment" / "Checking" text is gone
+            # AND there is some actual body content (not empty).
+            challenge_cleared = (
+                bool(body_text.strip())
+                and not any(p in text_lower for p in(
+                    "just a moment", "checking your browser", "attention required",
+                    "enable javascript and cookies",
+                ))
+            )
+
+            if challenge_cleared:
+                # Verify cf_clearance cookie was set
+                cookies = await session.get_cookies()
+                cf_clearance = [c for c in cookies if c.get("name") == "cf_clearance"]
+                if cf_clearance:
+                    return CaptchaResult(
+                        captcha_type=CaptchaType.CLOUDFLARE_JS,
+                        solved=True,
+                        cookie_name="cf_clearance",
+                        solver_used="cloudflare_auto",
+                        duration_seconds=elapsed,
+                    )
+                # Challenge cleared but no cookie — might be a lighter check
+                return CaptchaResult(
+                    captcha_type=CaptchaType.CLOUDFLARE_JS,
+                    solved=True,
+                    cookie_name=None,
+                    solver_used="cloudflare_auto",
+                    duration_seconds=elapsed,
+                )
+
+            await asyncio.sleep(self.poll_interval)
+
+        # Timed out
+        return CaptchaResult(
+            captcha_type=CaptchaType.CLOUDFLARE_JS,
+            solved=False,
+            error=f"Cloudflare challenge did not auto-resolve within {self.max_wait}s. "
+                  "The IP may be flagged or a Turnstile click may be required.",
+            duration_seconds=time.monotonic() - start,
+        )
+
+
+# ── Handler ───────────────────────────────────────────────────────────
+
+
+class CaptchaHandler:
+    """Detect and attempt to solve CAPTCHAs automatically.
+
+    Priority:
+      1. Cloudflare JS challenge → CloudflareAutoSolver (native JS execution)
+      2. Turnstile / reCAPTCHA / hCaptcha → external solver (if registered)
+      3. Generic → report and suggest manual intervention
+
+    Usage::
+
+        handler = CaptchaHandler(
+            auto_solver=CloudflareAutoSolver(),
+            external_solver=MySolver(),  # optional
+        )
+        result = await handler.detect_and_solve(session)
+    """
+
+    def __init__(
+        self,
+        auto_solver: CloudflareAutoSolver | None = None,
+        external_solver: CaptchaSolver | None = None,
+    ):
+        self.auto_solver = auto_solver or CloudflareAutoSolver()
+        self.external_solver = external_solver
+
+    async def detect_and_solve(self, session) -> CaptchaResult:
+        """Detect the CAPTCHA type and attempt resolution.
+
+        Returns a CaptchaResult. If solved, the session is ready to continue.
+        If not solved, the result contains the type and an error message.
+        """
+        start = time.monotonic()
+
+        # ── Detect ──────────────────────────────────────────────────
+        captcha_type = await detect_captcha(session)
+
+        if captcha_type == CaptchaType.NONE:
+            return CaptchaResult(
+                captcha_type=CaptchaType.NONE,
+                solved=True,
+                duration_seconds=time.monotonic() - start,
+            )
+
+        logger.info("CAPTCHA detected: %s", captcha_type.value)
+
+        # ── Cloudflare JS challenge → auto-solve ───────────────────
+        if captcha_type == CaptchaType.CLOUDFLARE_JS:
+            result = await self.auto_solver.solve(session)
+            return result
+
+        # ── External solver for reCAPTCHA/hCaptcha/Turnstile ───────
+        if self.external_solver and captcha_type in(
+            CaptchaType.RECAPTCHA_V2,
+            CaptchaType.RECAPTCHA_V3,
+            CaptchaType.HCAPTCHA,
+            CaptchaType.CLOUDFLARE_TURNSTILE,
+        ):
+            # Extract the site key
+            site_key = await session.evaluate(
+                "document.querySelector('[data-sitekey]')?.getAttribute('data-sitekey') || "
+                "document.querySelector('iframe[src*=\"recaptcha\"]')?.src.match(/render=([^&]+)/)?.[1] || "
+                "document.querySelector('iframe[src*=\"hcaptcha\"]')?.src.match(/sitekey=([^&]+)/)?.[1] || ''"
+            ) or ""
+
+            url = session._current_url
+
+            try:
+                token = await self.external_solver.solve(captcha_type, site_key or None, url)
+                if token:
+                    # Inject the token into the page
+                    await session.evaluate(
+                        f"document.getElementById('g-recaptcha-response').value = '{token}';"
+                        if captcha_type == CaptchaType.RECAPTCHA_V2 else
+                        f"window.__captcha_token__ = '{token}';"
+                    )
+                    return CaptchaResult(
+                        captcha_type=captcha_type,
+                        solved=True,
+                        solver_used="external",
+                        duration_seconds=time.monotonic() - start,
+                    )
+            except Exception as exc:
+                logger.warning("External solver failed: %s", exc)
+                return CaptchaResult(
+                    captcha_type=captcha_type,
+                    solved=False,
+                    error=f"External solver error: {exc}",
+                    duration_seconds=time.monotonic() - start,
+                )
+
+        # ── No solver available for this type ──────────────────────
+        solver_name = "external" if self.external_solver else "none"
+        return CaptchaResult(
+            captcha_type=captcha_type,
+            solved=False,
+            error=f"No solver available for {captcha_type.value} "
+                  f"(registered: {solver_name}). For Cloudflare JS challenges, "
+                  f"ensure real Chrome is used (not Lightpanda).",
+            duration_seconds=time.monotonic() - start,
+        )

ricibrowser/cdp_client.py

@@ -0,0 +1,261 @@
+"""Minimal CDP (Chrome DevTools Protocol) WebSocket client.
+
+Built from the public CDP specification at
+chromedevtools.github.io/devtools-protocol/. No Playwright, Puppeteer, or
+selenium dependency — just WebSocket + JSON-RPC.
+
+This client implements:
+  - WebSocket connection to a CDP endpoint (Chrome's /devtools/page/<id> or
+    Lightpanda's root ws://host:port)
+  - JSON-RPC command/response matching by id
+  - CDP event subscription via callback
+  - Target discovery via HTTP /json endpoint
+
+It does NOT implement:
+  - Runtime.enable on the main world (we use isolated worlds for JS eval)
+  - Console.enable by default (off — detection vector)
+  - Any browser-specific logic (that's in chrome_launcher.py / lightpanda.py)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Awaitable, Callable
+
+import httpx
+import websockets
+from websockets.asyncio.client import connect as ws_connect
+
+logger = logging.getLogger(__name__)
+
+CDPEventCallback = Callable[[dict[str, Any]], Awaitable[None] | None]
+
+
+class CDPError(Exception):
+    """CDP protocol error (method returned an error response)."""
+
+    def __init__(self, method: str, code: int, message: str, data: Any = None):
+        self.method = method
+        self.code = code
+        self.message = message
+        self.data = data
+        super().__init__(f"CDP {method} failed ({code}): {message}")
+
+
+class CDPClient:
+    """Low-level CDP WebSocket client.
+
+    Usage::
+
+        client = await CDPClient.connect("ws://127.0.0.1:9222")
+        result = await client.send("Page.navigate", {"url": "https://example.com"})
+        await client.close()
+
+    For Chrome (which uses target-level WS endpoints), use :meth:`connect_to_target`
+    which discovers targets via the HTTP /json API first.
+    """
+
+    def __init__(self, ws: websockets.WebSocketClientProtocol):
+        self._ws = ws
+        self._msg_id: int = 0
+        self._pending: dict[int, asyncio.Future[dict]] = {}
+        self._event_handlers: dict[str, list[CDPEventCallback]] = {}
+        self._recv_task: asyncio.Task | None = None
+        self._closed = False
+
+    @classmethod
+    async def connect(cls, ws_url: str) -> "CDPClient":
+        """Connect directly to a CDP WebSocket endpoint.
+
+        For Lightpanda: ws_url = "ws://127.0.0.1:9222"
+        For Chrome: ws_url = "ws://127.0.0.1:9223/devtools/page/<target_id>"
+        """
+        ws = await ws_connect(ws_url, max_size=50 * 1024 * 1024)  # 50 MB max
+        client = cls(ws)
+        client._recv_task = asyncio.create_task(client._recv_loop())
+        return client
+
+    @classmethod
+    async def connect_to_target(
+        cls,
+        http_url: str,
+        target_id: str | None = None,
+    ) -> "CDPClient":
+        """Connect to a Chrome CDP target discovered via the HTTP /json API.
+
+        1. GET /json to list targets (or /json/list)
+        2. Find a page-type target (or the one matching target_id)
+        3. Connect to its webSocketDebuggerUrl
+        """
+        # Fetch target list
+        async with httpx.AsyncClient(timeout=10.0) as http:
+            resp = await http.get(f"{http_url}/json")
+            if resp.status_code != 200:
+                raise CDPError("connect_to_target", resp.status_code, f"HTTP {resp.status_code}")
+            targets = resp.json()
+
+        # Find the target
+        target = None
+        if target_id:
+            # When a specific target_id is requested, search exclusively for it.
+            # Don't fall back to "first page target" — that could match an
+            # unrelated tab.
+            for t in targets:
+                if t.get("id") == target_id:
+                    target = t
+                    break
+            if target is None:
+                raise CDPError("connect_to_target", -1,
+                               f"Target {target_id} not found in CDP target list")
+        else:
+            for t in targets:
+                if t.get("type") == "page":
+                    target = t
+                    break
+
+        if target is None:
+            # Create a new tab if none exists
+            async with httpx.AsyncClient(timeout=10.0) as http:
+                resp = await http.put(f"{http_url}/json/new")
+                if resp.status_code in (200, 201):
+                    target = resp.json()
+
+        if target is None:
+            raise CDPError("connect_to_target", -1, "No CDP page target found and could not create one")
+
+        ws_url = target.get("webSocketDebuggerUrl")
+        if not ws_url:
+            raise CDPError("connect_to_target", -1, "Target has no webSocketDebuggerUrl")
+
+        return await cls.connect(ws_url)
+
+    async def send(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Send a CDP command and await the response.
+
+        Args:
+            method: CDP method name (e.g. "Page.navigate", "Runtime.evaluate")
+            params: Method parameters (default empty dict)
+
+        Returns:
+            The "result" field from the CDP response.
+
+        Raises:
+            CDPError: If the CDP response contains an error.
+        """
+        if self._closed:
+            raise CDPError(method, -1, "CDP client is closed")
+
+        self._msg_id += 1
+        msg_id = self._msg_id
+        msg: dict[str, Any] = {"id": msg_id, "method": method}
+        if params:
+            msg["params"] = params
+
+        future: asyncio.Future[dict] = asyncio.get_event_loop().create_future()
+        self._pending[msg_id] = future
+
+        try:
+            await self._ws.send(json.dumps(msg))
+        except Exception as exc:
+            self._pending.pop(msg_id, None)
+            raise CDPError(method, -1, f"WebSocket send failed: {exc}") from exc
+
+        try:
+            result = await asyncio.wait_for(future, timeout=120.0)
+            return result
+        except asyncio.TimeoutError:
+            self._pending.pop(msg_id, None)
+            raise CDPError(method, -1, f"Timeout waiting for response to {method}")
+
+    async def on_event(self, event_name: str, callback: CDPEventCallback) -> None:
+        """Register a callback for a CDP event (e.g. "Page.loadEventFired").
+
+        Callbacks can be sync or async. Multiple callbacks per event are supported.
+        """
+        self._event_handlers.setdefault(event_name, []).append(callback)
+
+    async def _recv_loop(self) -> None:
+        """Background task that reads WebSocket messages and dispatches them."""
+        try:
+            async for raw in self._ws:
+                if self._closed:
+                    break
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    logger.warning("CDP: received non-JSON message: %s", raw[:200])
+                    continue
+
+                # Response to a command (has "id")
+                if "id" in msg:
+                    fut = self._pending.pop(msg["id"], None)
+                    if fut is None:
+                        logger.warning("CDP: received response for unknown id %s", msg["id"])
+                        continue
+                    if "error" in msg:
+                        err = msg["error"]
+                        fut.set_exception(CDPError(
+                            method="<response>",
+                            code=err.get("code", -1),
+                            message=err.get("message", "Unknown error"),
+                            data=err.get("data"),
+                        ))
+                    else:
+                        fut.set_result(msg.get("result", {}))
+                    continue
+
+                # Event (has "method", no "id")
+                if "method" in msg:
+                    event_name = msg["method"]
+                    handlers = self._event_handlers.get(event_name, [])
+                    for handler in handlers:
+                        try:
+                            result = handler(msg.get("params", {}))
+                            if asyncio.iscoroutine(result):
+                                asyncio.create_task(result)
+                        except Exception:
+                            logger.exception("CDP: event handler for %s raised", event_name)
+        except websockets.ConnectionClosed:
+            pass
+        except Exception:
+            logger.exception("CDP: recv loop crashed")
+        finally:
+            # Mark as closed so send() fast-fails and callers reconnect
+            # instead of queuing futures that will never resolve.
+            self._closed = True
+            # Reject any pending futures
+            for fut in list(self._pending.values()):
+                if not fut.done():
+                    fut.set_exception(CDPError("<recv-closed>", -1, "Connection closed"))
+            self._pending.clear()
+
+    async def close(self) -> None:
+        """Close the WebSocket connection and stop the recv task."""
+        if self._closed:
+            return
+        self._closed = True
+        if self._recv_task and not self._recv_task.done():
+            self._recv_task.cancel()
+            try:
+                await asyncio.wait_for(self._recv_task, timeout=5.0)
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                pass
+        try:
+            await self._ws.close()
+        except Exception:
+            pass
+
+    @staticmethod
+    async def discover_targets(http_url: str) -> list[dict[str, Any]]:
+        """List CDP targets via the HTTP /json endpoint.
+
+        Returns a list of target dicts with keys: id, type, title, url,
+        webSocketDebuggerUrl, etc.
+        """
+        async with httpx.AsyncClient(timeout=10.0) as http:
+            resp = await http.get(f"{http_url}/json")
+            if resp.status_code == 200:
+                return resp.json()
+        return []