real-browser-cli 0.14.2__py3-none-any.whl

browser_cli/remote/transport.py

@@ -0,0 +1,230 @@
+"""TCP/TLS transport for talking to a remote ``browser-cli serve``.
+
+Owns the wire mechanics of the remote leg: open a socket (TLS on :443),
+complete the signed challenge/response handshake with an optional post-quantum
+key exchange, frame the request, and read the framed (possibly encrypted)
+response. The higher-level "which endpoint / which profile / which key"
+decisions stay in :mod:`browser_cli.client.core`.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+import sys
+from collections.abc import Callable
+from contextlib import contextmanager
+from typing import TypeVar
+
+from browser_cli.errors import BrowserNotConnected
+from browser_cli.endpoints import _resolve_connect_endpoint
+from browser_cli.framing import async_recv_exact, async_recv_frame, async_send_frame, frame, recv_exact, recv_frame
+from browser_cli.version_manager import USER_AGENT as _USER_AGENT
+
+T = TypeVar("T")
+_AUTH_FIELDS = {"token", "pubkey", "sig", "pq_kex", "encrypted", "_suppress_pq_warning"}
+_PQ_WARNING = (
+  "** WARNING: connection is not using a post-quantum key exchange algorithm.\n"
+  "** This session may be vulnerable to store now, decrypt later attacks.\n"
+)
+
+def _recv_exact(sock: socket.socket, n: int) -> bytes:
+  return recv_exact(sock, n) or b""
+
+def _recv_all(sock: socket.socket) -> bytes:
+  return recv_frame(sock, label="Response") or b""
+
+async def _async_recv_exact(reader: asyncio.StreamReader, n: int) -> bytes:
+  return await async_recv_exact(reader, n) or b""
+
+async def _async_recv_all(reader: asyncio.StreamReader) -> bytes:
+  return await async_recv_frame(reader, label="Response") or b""
+
+def _split_endpoint(endpoint: str) -> tuple[str, int]:
+  connect_ep = _resolve_connect_endpoint(endpoint)
+  host, _, port_str = connect_ep.rpartition(":")
+  return host, int(port_str)
+
+@contextmanager
+def _open_socket(endpoint: str):
+  host, port = _split_endpoint(endpoint)
+  raw_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+  raw_sock.settimeout(30)
+  try:
+    raw_sock.connect((host, port))
+    if port == 443:
+      import ssl
+      sock = ssl.create_default_context().wrap_socket(raw_sock, server_hostname=host)
+    else:
+      sock = raw_sock
+  except Exception:
+    raw_sock.close()
+    raise
+  with sock:
+    yield sock
+
+async def _open_async_connection(endpoint: str) -> tuple[asyncio.StreamReader, asyncio.StreamWriter]:
+  host, port = _split_endpoint(endpoint)
+  ssl_ctx = None
+  if port == 443:
+    import ssl
+    ssl_ctx = ssl.create_default_context()
+  return await asyncio.open_connection(host, port, ssl=ssl_ctx, server_hostname=host if ssl_ctx else None)
+
+def _parse_challenge(raw: bytes) -> tuple[dict | None, str | None]:
+  try:
+    challenge = json.loads(raw)
+    nonce_hex = challenge.get("nonce") if challenge.get("type") == "challenge" else None
+    return challenge, nonce_hex
+  except (json.JSONDecodeError, AttributeError):
+    return None, None
+
+def _check_min_client_version(challenge: dict | None) -> None:
+  min_ver = challenge.get("min_client_version") if isinstance(challenge, dict) else None
+  if not min_ver:
+    return
+  from browser_cli.version_manager import parse_version
+  try:
+    client_ver = _USER_AGENT.split("/", 1)[1]
+    if parse_version(client_ver) < parse_version(min_ver):
+      raise BrowserNotConnected(
+        f"Client version {client_ver} is too old for this server "
+        f"(requires >= {min_ver}). Run: pip install --upgrade browser-cli"
+      )
+  except (IndexError, ValueError):
+    pass
+
+def _clean_message(msg: dict) -> dict:
+  return {k: v for k, v in msg.items() if k not in _AUTH_FIELDS}
+
+def _get_pq_public_key(challenge: dict | None) -> str | None:
+  if not isinstance(challenge, dict):
+    return None
+  from browser_cli.auth import PQ_KEX_ALG
+  kex = challenge.get("pq_kex")
+  if isinstance(kex, dict) and kex.get("alg") == PQ_KEX_ALG and kex.get("public_key"):
+    return str(kex["public_key"])
+  return None
+
+def _signed_payload(clean_msg: dict, private_key, nonce_hex: str, pq_shared_secret: bytes | None) -> dict:
+  from browser_cli.auth import PQ_KEX_ALG, pq_encrypt, public_key_hex, sign
+
+  nonce = bytes.fromhex(nonce_hex)
+  sig = sign(private_key, nonce, clean_msg, pq_shared_secret)
+  pubkey = public_key_hex(private_key)
+  if pq_shared_secret is None:
+    return {**clean_msg, "pubkey": pubkey, "sig": sig.hex()}
+
+  encrypted = pq_encrypt(pq_shared_secret, "request", json.dumps(clean_msg).encode("utf-8"))
+  return {
+    "id": clean_msg.get("id"),
+    "user_agent": clean_msg.get("user_agent"),
+    "pubkey": pubkey,
+    "sig": sig.hex(),
+    "pq_kex": clean_msg["pq_kex"],
+    "encrypted": encrypted,
+  }
+
+def _warn_no_pq(enabled: bool) -> None:
+  if enabled:
+    sys.stderr.write(_PQ_WARNING)
+
+def _build_auth_message(
+  msg: dict,
+  challenge: dict | None,
+  nonce_hex: str | None,
+  private_key,
+  encapsulate: Callable[[str], tuple[str, bytes]],
+  *,
+  warn_no_pq: bool = True,
+) -> tuple[dict, bytes | None]:
+  if not nonce_hex or private_key is None:
+    _warn_no_pq(warn_no_pq)
+    return msg, None
+
+  clean_msg = _clean_message(msg)
+  pq_shared_secret = None
+  pq_public_key = _get_pq_public_key(challenge)
+  if pq_public_key:
+    from browser_cli.auth import PQ_KEX_ALG
+    ciphertext_hex, pq_shared_secret = encapsulate(pq_public_key)
+    clean_msg["pq_kex"] = {"alg": PQ_KEX_ALG, "ciphertext": ciphertext_hex}
+  else:
+    _warn_no_pq(warn_no_pq)
+
+  return _signed_payload(clean_msg, private_key, nonce_hex, pq_shared_secret), pq_shared_secret
+
+async def _build_auth_message_async(
+  msg: dict,
+  challenge: dict | None,
+  nonce_hex: str | None,
+  private_key,
+  *,
+  warn_no_pq: bool = True,
+) -> tuple[dict, bytes | None]:
+  def encapsulate(public_key: str) -> tuple[str, bytes]:
+    from browser_cli.auth import pq_kex_client_encapsulate
+    return pq_kex_client_encapsulate(public_key)
+
+  return await asyncio.to_thread(
+    _build_auth_message,
+    msg,
+    challenge,
+    nonce_hex,
+    private_key,
+    encapsulate,
+    warn_no_pq=warn_no_pq,
+  )
+
+def _decode_pq_response(response: bytes | None, pq_shared_secret: bytes | None) -> bytes | None:
+  if response is None or pq_shared_secret is None:
+    return response
+  try:
+    from browser_cli.auth import pq_decrypt
+    envelope = json.loads(response)
+    if isinstance(envelope, dict) and "encrypted" in envelope:
+      return pq_decrypt(pq_shared_secret, "response", envelope["encrypted"])
+  except Exception as e:
+    raise BrowserNotConnected(f"Cannot decrypt post-quantum remote response: {e}") from e
+  return response
+
+def _with_challenge(challenge_raw: bytes, msg: dict, private_key, build_auth: Callable[[dict, dict | None, str | None, object], T]) -> T:
+  if challenge_raw is None:
+    raise BrowserNotConnected("No challenge received from remote endpoint")
+  challenge, nonce_hex = _parse_challenge(challenge_raw)
+  _check_min_client_version(challenge)
+  return build_auth(msg, challenge, nonce_hex, private_key)
+
+def _should_warn_no_pq(msg: dict) -> bool:
+  return not bool(msg.pop("_suppress_pq_warning", False))
+
+async def _send_remote_async(endpoint: str, msg: dict, private_key=None, *, warn_no_pq: bool | None = None) -> bytes | None:
+  reader, writer = await _open_async_connection(endpoint)
+  try:
+    challenge_raw = await _async_recv_all(reader)
+    warn = _should_warn_no_pq(msg) if warn_no_pq is None else warn_no_pq
+
+    async def build_auth(sync_msg: dict, challenge: dict | None, nonce_hex: str | None, key):
+      return await _build_auth_message_async(sync_msg, challenge, nonce_hex, key, warn_no_pq=warn)
+
+    payload_msg, pq_shared_secret = await _with_challenge(challenge_raw, msg, private_key, build_auth)
+    await async_send_frame(writer, json.dumps(payload_msg).encode("utf-8"))
+    return _decode_pq_response(await _async_recv_all(reader), pq_shared_secret)
+  finally:
+    writer.close()
+    try:
+      await writer.wait_closed()
+    except Exception:
+      pass
+
+def _send_remote(endpoint: str, msg: dict, private_key=None, *, warn_no_pq: bool | None = None) -> bytes | None:
+  warn = _should_warn_no_pq(msg) if warn_no_pq is None else warn_no_pq
+
+  def build_auth(sync_msg: dict, challenge: dict | None, nonce_hex: str | None, key):
+    from browser_cli.auth import pq_kex_client_encapsulate
+    return _build_auth_message(sync_msg, challenge, nonce_hex, key, pq_kex_client_encapsulate, warn_no_pq=warn)
+
+  with _open_socket(endpoint) as sock:
+    payload_msg, pq_shared_secret = _with_challenge(_recv_all(sock), msg, private_key, build_auth)
+    sock.sendall(frame(json.dumps(payload_msg).encode("utf-8")))
+    return _decode_pq_response(_recv_all(sock), pq_shared_secret)

browser_cli/sdk/__init__.py

@@ -0,0 +1,48 @@
+"""SDK command namespaces for :class:`browser_cli.BrowserCLI`.
+
+Each namespace groups related browser commands under a short accessor on the
+client (``b.tabs``, ``b.dom``, ``b.session``, ...), mirroring the command groups
+in the browser extension.
+"""
+from browser_cli.sdk.browser_data import StorageNS
+from browser_cli.sdk.decorators import DecoratorsNS
+from browser_cli.sdk.dom import DomNS, ExtractNS, PageNS
+from browser_cli.sdk.extension import ExtensionNS
+from browser_cli.sdk.groups import GroupsNS
+from browser_cli.sdk.navigation import NavigationNS
+from browser_cli.sdk.perf import PerfNS
+from browser_cli.sdk.session import SessionNS
+from browser_cli.sdk.tabs import TabsNS
+from browser_cli.sdk.windows import WindowsNS
+
+NAMESPACE_SPECS = (
+    ("nav", NavigationNS),
+    ("tabs", TabsNS),
+    ("groups", GroupsNS),
+    ("windows", WindowsNS),
+    ("dom", DomNS),
+    ("extract", ExtractNS),
+    ("page", PageNS),
+    ("storage", StorageNS),
+    ("session", SessionNS),
+    ("perf", PerfNS),
+    ("extension", ExtensionNS),
+)
+NAMESPACE_NAMES = tuple(name for name, _ in NAMESPACE_SPECS)
+
+__all__ = [
+    "NavigationNS",
+    "TabsNS",
+    "GroupsNS",
+    "WindowsNS",
+    "DomNS",
+    "ExtractNS",
+    "PageNS",
+    "StorageNS",
+    "SessionNS",
+    "PerfNS",
+    "ExtensionNS",
+    "DecoratorsNS",
+    "NAMESPACE_SPECS",
+    "NAMESPACE_NAMES",
+]

browser_cli/sdk/base.py

@@ -0,0 +1,116 @@
+"""Base helpers for SDK command namespaces.
+
+Each namespace (``b.tabs``, ``b.dom``, ...) is a thin object bound to its
+:class:`~browser_cli.BrowserCLI` client. Namespaces hold no state of their own;
+they delegate to the client's shared infrastructure (command dispatch, the
+multi-browser helpers, and the ``Tab``/``Group`` factories).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable)
+_MISSING = object()
+
+def _clone_default(value):
+  if isinstance(value, (dict, list, set)):
+    return value.copy()
+  return value
+
+def sdk_command(
+  name: str,
+  args: Callable | None = None,
+  *,
+  default=_MISSING,
+  field: str | None = None,
+  fallback=_MISSING,
+  mapper: Callable | None = None,
+  return_result: bool = True,
+):
+  """Decorate a namespace method as a browser wire command.
+
+  This keeps the public method signature/docstring on the normal Python
+  method, while moving repetitive command-dispatch plumbing into one place.
+  The wrapped function body is intentionally unused; it exists only for
+  signature, docs, and type hints.
+  """
+
+  def decorator(func: F) -> F:
+    @wraps(func)
+    def wrapper(self, *method_args, **method_kwargs):
+      payload = args(self, *method_args, **method_kwargs) if args is not None else {}
+      result = self.command(name, payload)
+      if not return_result:
+        return None
+      if mapper is not None:
+        return mapper(self, result, *method_args, **method_kwargs)
+      if field is not None:
+        if fallback is _MISSING:
+          return self.field(result, field, default)
+        return self.field(result, field, default, fallback=fallback)
+      if default is not _MISSING and not result:
+        return _clone_default(default)
+      return result
+
+    wrapper._browser_cli_command = name  # type: ignore[attr-defined]
+    return wrapper  # type: ignore[return-value]
+
+  return decorator
+
+class Namespace:
+  """A group of related SDK methods, bound to a BrowserCLI client."""
+
+  def __init__(self, client: Any):
+    self._c = client
+
+  def command(self, name: str, args: dict | None = None):
+    """Dispatch a browser command through the owning client."""
+    return self._c.dispatch(name, args)
+
+  def tab_from(self, data: dict):
+    """Build a bound Tab from a raw command response dict."""
+    return self._c.tab_from(data)
+
+  def group_from(self, data: dict):
+    """Build a bound Group from a raw command response dict."""
+    return self._c.group_from(data)
+
+  def tab_from_target(self, data: dict, target):
+    """Build a bound Tab for a multi-browser target."""
+    return self._c.tab_from_target(data, target)
+
+  def group_from_target(self, data: dict, target):
+    """Build a bound Group for a multi-browser target."""
+    return self._c.group_from_target(data, target)
+
+  def tag_browser(self, item: dict, target):
+    """Annotate a raw dict with its browser in multi-browser mode."""
+    return self._c.tag_browser(item, target)
+
+  def multi_list(self, name: str, args: dict | None, mapper: Callable):
+    """Run a list command with multi-browser fan-out support."""
+    return self._c.multi_list(name, args, mapper)
+
+  def multi_count(self, name: str, args: dict | None = None):
+    """Run a count command with multi-browser fan-out support."""
+    return self._c.multi_count(name, args)
+
+  def apply_tab_filter(self, filter_fn: Callable):
+    """Apply a Python-side tab filter using client semantics."""
+    return self._c.apply_tab_filter(filter_fn)
+
+  def toggle_tab(self, name: str, tab_id: int | None):
+    """Run a tab toggle command and return the affected tab ID."""
+    return self._c.toggle_tab(name, tab_id)
+
+  def require_tab(self, data, error: str):
+    """Convert a tab-like response into a bound Tab or raise a clean error."""
+    return self._c.require_tab(data, error)
+
+  def field(self, result, key, default=None, *, fallback=_MISSING):
+    """Read a field from command output using the client's SDK semantics."""
+    if fallback is _MISSING:
+      return self._c.field(result, key, default)
+    return self._c.field(result, key, default, fallback=fallback)

browser_cli/sdk/browser_data.py

@@ -0,0 +1,37 @@
+"""Storage namespace: ``b.storage.*``."""
+from __future__ import annotations
+
+from browser_cli.sdk.base import Namespace, sdk_command
+
+class StorageNS(Namespace):
+  """Read and write localStorage / sessionStorage."""
+
+  @sdk_command("storage.get", lambda self, key=None, *, type="local", tab_id=None: {
+    "key": key,
+    "type": type,
+    "tabId": tab_id,
+  })
+  def get(
+    self,
+    key: str | None = None,
+    *,
+    type: str = "local",
+    tab_id: int | None = None,
+  ) -> str | dict | None:
+    """Get a localStorage/sessionStorage entry (or all entries if key omitted)."""
+
+  @sdk_command("storage.set", lambda self, key, value, *, type="local", tab_id=None: {
+    "key": key,
+    "value": value,
+    "type": type,
+    "tabId": tab_id,
+  })
+  def set(
+    self,
+    key: str,
+    value: str,
+    *,
+    type: str = "local",
+    tab_id: int | None = None,
+  ) -> None:
+    """Set a localStorage/sessionStorage entry."""

browser_cli/sdk/decorators.py

@@ -0,0 +1,107 @@
+"""Synchronous workflow decorator namespace for the Python SDK."""
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from collections.abc import Callable
+from typing import TypeVar
+
+from browser_cli.sdk.base import Namespace
+from browser_cli.sdk.workflow_decorators import WorkflowDecoratorsMixin, _NO_INJECT
+
+F = TypeVar("F", bound=Callable)
+
+class DecoratorsNS(WorkflowDecoratorsMixin, Namespace):
+  """Workflow decorators bound to a :class:`browser_cli.BrowserCLI` client.
+
+  The normal SDK is synchronous, but these decorators also work on ``async def``
+  functions: browser operations run via ``asyncio.to_thread`` so the event loop
+  is not blocked while waiting for the browser response.
+  """
+
+  def _run(self, func: Callable, *args, **kwargs):
+    if inspect.iscoroutinefunction(func):
+      raise TypeError("sync BrowserCLI decorators cannot call async browser methods")
+    return func(*args, **kwargs)
+
+  def _call_wrapped(self, func: Callable, *args, **kwargs):
+    if inspect.iscoroutinefunction(func):
+      async def run_async():
+        return await func(*args, **kwargs)
+      return run_async()
+    return func(*args, **kwargs)
+
+  def _value_decorator(
+    self,
+    func: F | None,
+    get_value: Callable,
+    *,
+    keyword: str | None | object = "tab",
+    cleanup: Callable | None = None,
+  ):
+    def decorator(fn: F) -> F:
+      if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def async_wrapper(*args, **kwargs):
+          value = await asyncio.to_thread(get_value)
+          try:
+            extra_args = ()
+            if keyword is not _NO_INJECT:
+              extra_args, kwargs = self._inject(kwargs, keyword, value)
+            return await fn(*extra_args, *args, **kwargs)
+          finally:
+            if cleanup is not None:
+              await asyncio.to_thread(cleanup, value)
+        return async_wrapper  # type: ignore[return-value]
+      return WorkflowDecoratorsMixin._value_decorator(
+        self, fn, get_value, keyword=keyword, cleanup=cleanup
+      )
+
+    return decorator(func) if func is not None else decorator
+
+  def performance_profile(self, profile: str, *, restore: bool = True):
+    def decorator(fn: F) -> F:
+      if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def async_wrapper(*args, **kwargs):
+          previous = None
+          if restore:
+            previous = (await asyncio.to_thread(self._c.perf.status)).get("performanceProfile")
+          await asyncio.to_thread(self._c.perf.set_profile, profile)
+          try:
+            return await fn(*args, **kwargs)
+          finally:
+            if previous:
+              await asyncio.to_thread(self._c.perf.set_profile, previous)
+        return async_wrapper  # type: ignore[return-value]
+      return WorkflowDecoratorsMixin.performance_profile(self, profile, restore=restore)(fn)
+    return decorator
+
+  def retry(
+    self,
+    *,
+    times: int = 3,
+    delay: float = 0.0,
+    exceptions: tuple[type[BaseException], ...] = (Exception,),
+  ):
+    attempts = max(1, times)
+
+    def decorator(fn: F) -> F:
+      if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def async_wrapper(*args, **kwargs):
+          last_error = None
+          for attempt in range(attempts):
+            try:
+              return await fn(*args, **kwargs)
+            except exceptions as exc:
+              last_error = exc
+              if attempt == attempts - 1:
+                raise
+              if delay > 0:
+                await asyncio.sleep(delay)
+          raise last_error  # type: ignore[misc]
+        return async_wrapper  # type: ignore[return-value]
+      return WorkflowDecoratorsMixin.retry(self, times=times, delay=delay, exceptions=exceptions)(fn)
+    return decorator