parsek-cdp 0.1.0__py3-none-any.whl

parsek_cdp/cdp/webauthn/__init__.py

@@ -0,0 +1,15 @@
+"""The WebAuthn CDP domain (generated).
+
+Importing ``WebAuthn`` from ``parsek_cdp.cdp`` gives a namespace with this
+domain's events and types as attributes (``WebAuthn.SomeEvent`` /
+``WebAuthn.SomeType``); commands run on a target via ``page.cdp.WebAuthn``.
+"""
+from . import events, functions, types
+from .functions import WebAuthn
+from .events import *  # noqa: F401,F403 -- expose events on the namespace
+from .types import *  # noqa: F401,F403 -- expose types on the namespace
+
+#: Protocol domain name (used by features that declare ``domains=(WebAuthn,)``).
+DOMAIN = "WebAuthn"
+
+__all__ = ["events", "functions", "types", "WebAuthn", "DOMAIN"]

parsek_cdp/cdp/webauthn/events.py

@@ -0,0 +1,69 @@
+"""Events for the WebAuthn domain (generated)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Literal, Optional
+
+from ..mixins.datatype import FieldMeta
+from ..mixins.event import Event, register_event
+
+if TYPE_CHECKING:
+    from .types import (
+        AuthenticatorId,
+        Credential,
+    )
+
+@register_event("WebAuthn.credentialAdded")
+@dataclass
+class CredentialAdded(Event):
+    """Triggered when a credential is added to an authenticator."""
+    authenticator_id: AuthenticatorId
+    credential: Credential
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('authenticator_id', 'authenticatorId', False, 'primitive'),
+        FieldMeta('credential', 'credential', False, 'object', ref='WebAuthn.Credential'),
+    )
+
+
+@register_event("WebAuthn.credentialDeleted")
+@dataclass
+class CredentialDeleted(Event):
+    """
+    Triggered when a credential is deleted, e.g. through
+    PublicKeyCredential.signalUnknownCredential().
+    """
+    authenticator_id: AuthenticatorId
+    credential_id: str
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('authenticator_id', 'authenticatorId', False, 'primitive'),
+        FieldMeta('credential_id', 'credentialId', False, 'primitive'),
+    )
+
+
+@register_event("WebAuthn.credentialUpdated")
+@dataclass
+class CredentialUpdated(Event):
+    """
+    Triggered when a credential is updated, e.g. through
+    PublicKeyCredential.signalCurrentUserDetails().
+    """
+    authenticator_id: AuthenticatorId
+    credential: Credential
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('authenticator_id', 'authenticatorId', False, 'primitive'),
+        FieldMeta('credential', 'credential', False, 'object', ref='WebAuthn.Credential'),
+    )
+
+
+@register_event("WebAuthn.credentialAsserted")
+@dataclass
+class CredentialAsserted(Event):
+    """Triggered when a credential is used in a webauthn assertion."""
+    authenticator_id: AuthenticatorId
+    credential: Credential
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('authenticator_id', 'authenticatorId', False, 'primitive'),
+        FieldMeta('credential', 'credential', False, 'object', ref='WebAuthn.Credential'),
+    )
+
+__all__ = ["CredentialAdded", "CredentialAsserted", "CredentialDeleted", "CredentialUpdated"]

parsek_cdp/cdp/webauthn/functions.py

@@ -0,0 +1,214 @@
+"""Commands for the WebAuthn domain (generated)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, ClassVar, Dict, List, Literal, Optional
+
+from ..mixins.datatype import DataType, FieldMeta, encode
+
+if TYPE_CHECKING:
+    from .types import (
+        AuthenticatorId,
+        Credential,
+        VirtualAuthenticatorOptions,
+    )
+
+@dataclass
+class AddVirtualAuthenticatorReturn(DataType):
+    """Return value of :meth:`WebAuthn.add_virtual_authenticator`."""
+    authenticator_id: AuthenticatorId
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('authenticator_id', 'authenticatorId', False, 'primitive'),
+    )
+
+
+@dataclass
+class GetCredentialReturn(DataType):
+    """Return value of :meth:`WebAuthn.get_credential`."""
+    credential: Credential
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('credential', 'credential', False, 'object', ref='WebAuthn.Credential'),
+    )
+
+
+@dataclass
+class GetCredentialsReturn(DataType):
+    """Return value of :meth:`WebAuthn.get_credentials`."""
+    credentials: List[Credential]
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('credentials', 'credentials', False, 'array', inner=FieldMeta('', '', False, 'object', ref='WebAuthn.Credential')),
+    )
+
+
+class WebAuthn:
+    """Commands of the WebAuthn domain, bound to a target."""
+
+    def __init__(self, target: Any) -> None:
+        self._target = target
+
+
+    async def enable(self, *, enable_ui: Optional[bool] = None) -> None:
+        """
+        Enable the WebAuthn domain and start intercepting credential storage and
+        retrieval with a virtual authenticator.
+        :param enable_ui: Whether to enable the WebAuthn user interface. Enabling the UI is
+        recommended for debugging and demo purposes, as it is closer to the real
+        experience. Disabling the UI is recommended for automated testing.
+        Supported at the embedder's discretion if UI is available.
+        Defaults to false.
+        """
+        _params: Dict[str, Any] = {}
+        if enable_ui is not None:
+            _params['enableUI'] = encode(FieldMeta('', '', False, 'primitive'), enable_ui)
+        _result = await self._target.send('WebAuthn.enable', _params)
+        return None
+
+    async def disable(self) -> None:
+        """Disable the WebAuthn domain."""
+        _params: Dict[str, Any] = {}
+        _result = await self._target.send('WebAuthn.disable', _params)
+        return None
+
+    async def add_virtual_authenticator(self, *, options: VirtualAuthenticatorOptions) -> AddVirtualAuthenticatorReturn:
+        """
+        Creates and adds a virtual authenticator.
+        :param options:
+        """
+        _params: Dict[str, Any] = {}
+        _params['options'] = encode(FieldMeta('', '', False, 'object', ref='WebAuthn.VirtualAuthenticatorOptions'), options)
+        _result = await self._target.send('WebAuthn.addVirtualAuthenticator', _params)
+        return AddVirtualAuthenticatorReturn.from_json(_result)
+
+    async def set_response_override_bits(self, *, authenticator_id: AuthenticatorId, is_bogus_signature: Optional[bool] = None, is_bad_uv: Optional[bool] = None, is_bad_up: Optional[bool] = None) -> None:
+        """
+        Resets parameters isBogusSignature, isBadUV, isBadUP to false if they are not present.
+        :param authenticator_id:
+        :param is_bogus_signature: If isBogusSignature is set, overrides the signature in the authenticator response to be zero.
+        Defaults to false.
+        :param is_bad_uv: If isBadUV is set, overrides the UV bit in the flags in the authenticator response to
+        be zero. Defaults to false.
+        :param is_bad_up: If isBadUP is set, overrides the UP bit in the flags in the authenticator response to
+        be zero. Defaults to false.
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        if is_bogus_signature is not None:
+            _params['isBogusSignature'] = encode(FieldMeta('', '', False, 'primitive'), is_bogus_signature)
+        if is_bad_uv is not None:
+            _params['isBadUV'] = encode(FieldMeta('', '', False, 'primitive'), is_bad_uv)
+        if is_bad_up is not None:
+            _params['isBadUP'] = encode(FieldMeta('', '', False, 'primitive'), is_bad_up)
+        _result = await self._target.send('WebAuthn.setResponseOverrideBits', _params)
+        return None
+
+    async def remove_virtual_authenticator(self, *, authenticator_id: AuthenticatorId) -> None:
+        """
+        Removes the given authenticator.
+        :param authenticator_id:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _result = await self._target.send('WebAuthn.removeVirtualAuthenticator', _params)
+        return None
+
+    async def add_credential(self, *, authenticator_id: AuthenticatorId, credential: Credential) -> None:
+        """
+        Adds the credential to the specified authenticator.
+        :param authenticator_id:
+        :param credential:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _params['credential'] = encode(FieldMeta('', '', False, 'object', ref='WebAuthn.Credential'), credential)
+        _result = await self._target.send('WebAuthn.addCredential', _params)
+        return None
+
+    async def get_credential(self, *, authenticator_id: AuthenticatorId, credential_id: str) -> GetCredentialReturn:
+        """
+        Returns a single credential stored in the given virtual authenticator that
+        matches the credential ID.
+        :param authenticator_id:
+        :param credential_id:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _params['credentialId'] = encode(FieldMeta('', '', False, 'primitive'), credential_id)
+        _result = await self._target.send('WebAuthn.getCredential', _params)
+        return GetCredentialReturn.from_json(_result)
+
+    async def get_credentials(self, *, authenticator_id: AuthenticatorId) -> GetCredentialsReturn:
+        """
+        Returns all the credentials stored in the given virtual authenticator.
+        :param authenticator_id:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _result = await self._target.send('WebAuthn.getCredentials', _params)
+        return GetCredentialsReturn.from_json(_result)
+
+    async def remove_credential(self, *, authenticator_id: AuthenticatorId, credential_id: str) -> None:
+        """
+        Removes a credential from the authenticator.
+        :param authenticator_id:
+        :param credential_id:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _params['credentialId'] = encode(FieldMeta('', '', False, 'primitive'), credential_id)
+        _result = await self._target.send('WebAuthn.removeCredential', _params)
+        return None
+
+    async def clear_credentials(self, *, authenticator_id: AuthenticatorId) -> None:
+        """
+        Clears all the credentials from the specified device.
+        :param authenticator_id:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _result = await self._target.send('WebAuthn.clearCredentials', _params)
+        return None
+
+    async def set_user_verified(self, *, authenticator_id: AuthenticatorId, is_user_verified: bool) -> None:
+        """
+        Sets whether User Verification succeeds or fails for an authenticator.
+        The default is true.
+        :param authenticator_id:
+        :param is_user_verified:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _params['isUserVerified'] = encode(FieldMeta('', '', False, 'primitive'), is_user_verified)
+        _result = await self._target.send('WebAuthn.setUserVerified', _params)
+        return None
+
+    async def set_automatic_presence_simulation(self, *, authenticator_id: AuthenticatorId, enabled: bool) -> None:
+        """
+        Sets whether tests of user presence will succeed immediately (if true) or fail to resolve (if false) for an authenticator.
+        The default is true.
+        :param authenticator_id:
+        :param enabled:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _params['enabled'] = encode(FieldMeta('', '', False, 'primitive'), enabled)
+        _result = await self._target.send('WebAuthn.setAutomaticPresenceSimulation', _params)
+        return None
+
+    async def set_credential_properties(self, *, authenticator_id: AuthenticatorId, credential_id: str, backup_eligibility: Optional[bool] = None, backup_state: Optional[bool] = None) -> None:
+        """
+        Allows setting credential properties.
+        https://w3c.github.io/webauthn/#sctn-automation-set-credential-properties
+        :param authenticator_id:
+        :param credential_id:
+        :param backup_eligibility:
+        :param backup_state:
+        """
+        _params: Dict[str, Any] = {}
+        _params['authenticatorId'] = encode(FieldMeta('', '', False, 'primitive'), authenticator_id)
+        _params['credentialId'] = encode(FieldMeta('', '', False, 'primitive'), credential_id)
+        if backup_eligibility is not None:
+            _params['backupEligibility'] = encode(FieldMeta('', '', False, 'primitive'), backup_eligibility)
+        if backup_state is not None:
+            _params['backupState'] = encode(FieldMeta('', '', False, 'primitive'), backup_state)
+        _result = await self._target.send('WebAuthn.setCredentialProperties', _params)
+        return None

parsek_cdp/cdp/webauthn/types.py

@@ -0,0 +1,96 @@
+"""Custom types and enums for the WebAuthn domain (generated)."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, ClassVar, Dict, List, Literal, Optional
+
+from ..mixins.datatype import DataType, FieldMeta, register
+
+
+type AuthenticatorId = str
+
+
+@register("WebAuthn.AuthenticatorProtocol")
+class AuthenticatorProtocol(str, Enum):
+    U2F = 'u2f'
+    CTAP2 = 'ctap2'
+
+
+@register("WebAuthn.Ctap2Version")
+class Ctap2Version(str, Enum):
+    CTAP2_0 = 'ctap2_0'
+    CTAP2_1 = 'ctap2_1'
+
+
+@register("WebAuthn.AuthenticatorTransport")
+class AuthenticatorTransport(str, Enum):
+    USB = 'usb'
+    NFC = 'nfc'
+    BLE = 'ble'
+    CABLE = 'cable'
+    INTERNAL = 'internal'
+
+
+@register("WebAuthn.VirtualAuthenticatorOptions")
+@dataclass
+class VirtualAuthenticatorOptions(DataType):
+    protocol: AuthenticatorProtocol
+    transport: AuthenticatorTransport
+    ctap2_version: Optional[Ctap2Version] = None
+    has_resident_key: Optional[bool] = None
+    has_user_verification: Optional[bool] = None
+    has_large_blob: Optional[bool] = None
+    has_cred_blob: Optional[bool] = None
+    has_min_pin_length: Optional[bool] = None
+    has_prf: Optional[bool] = None
+    automatic_presence_simulation: Optional[bool] = None
+    is_user_verified: Optional[bool] = None
+    default_backup_eligibility: Optional[bool] = None
+    default_backup_state: Optional[bool] = None
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('protocol', 'protocol', False, 'enum', ref='WebAuthn.AuthenticatorProtocol'),
+        FieldMeta('transport', 'transport', False, 'enum', ref='WebAuthn.AuthenticatorTransport'),
+        FieldMeta('ctap2_version', 'ctap2Version', True, 'enum', ref='WebAuthn.Ctap2Version'),
+        FieldMeta('has_resident_key', 'hasResidentKey', True, 'primitive'),
+        FieldMeta('has_user_verification', 'hasUserVerification', True, 'primitive'),
+        FieldMeta('has_large_blob', 'hasLargeBlob', True, 'primitive'),
+        FieldMeta('has_cred_blob', 'hasCredBlob', True, 'primitive'),
+        FieldMeta('has_min_pin_length', 'hasMinPinLength', True, 'primitive'),
+        FieldMeta('has_prf', 'hasPrf', True, 'primitive'),
+        FieldMeta('automatic_presence_simulation', 'automaticPresenceSimulation', True, 'primitive'),
+        FieldMeta('is_user_verified', 'isUserVerified', True, 'primitive'),
+        FieldMeta('default_backup_eligibility', 'defaultBackupEligibility', True, 'primitive'),
+        FieldMeta('default_backup_state', 'defaultBackupState', True, 'primitive'),
+    )
+
+
+@register("WebAuthn.Credential")
+@dataclass
+class Credential(DataType):
+    credential_id: str
+    is_resident_credential: bool
+    private_key: str
+    sign_count: int
+    rp_id: Optional[str] = None
+    user_handle: Optional[str] = None
+    large_blob: Optional[str] = None
+    backup_eligibility: Optional[bool] = None
+    backup_state: Optional[bool] = None
+    user_name: Optional[str] = None
+    user_display_name: Optional[str] = None
+    __FIELDS__: ClassVar[tuple] = (
+        FieldMeta('credential_id', 'credentialId', False, 'primitive'),
+        FieldMeta('is_resident_credential', 'isResidentCredential', False, 'primitive'),
+        FieldMeta('private_key', 'privateKey', False, 'primitive'),
+        FieldMeta('sign_count', 'signCount', False, 'primitive'),
+        FieldMeta('rp_id', 'rpId', True, 'primitive'),
+        FieldMeta('user_handle', 'userHandle', True, 'primitive'),
+        FieldMeta('large_blob', 'largeBlob', True, 'primitive'),
+        FieldMeta('backup_eligibility', 'backupEligibility', True, 'primitive'),
+        FieldMeta('backup_state', 'backupState', True, 'primitive'),
+        FieldMeta('user_name', 'userName', True, 'primitive'),
+        FieldMeta('user_display_name', 'userDisplayName', True, 'primitive'),
+    )
+
+__all__ = ["AuthenticatorId", "AuthenticatorProtocol", "AuthenticatorTransport", "Credential", "Ctap2Version", "VirtualAuthenticatorOptions"]

parsek_cdp/core/__init__.py

@@ -0,0 +1,18 @@
+"""Core runtime: connection, targets, browser, page and request tracking."""
+
+from .browser import Browser
+from .browser_context import BrowserContext
+from .element import Element
+from .feature import Feature
+from .page import Page
+from .target import ProtocolError, Target
+
+__all__ = [
+    "Browser",
+    "BrowserContext",
+    "Element",
+    "Feature",
+    "Page",
+    "ProtocolError",
+    "Target",
+]

parsek_cdp/core/browser.py

@@ -0,0 +1,240 @@
+"""Browser-level target: the websocket endpoint and target management."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import urllib.parse
+import urllib.request
+from typing import ClassVar, List, Optional
+
+from ..cdp import CDP
+from ..cdp import Target as TargetDomain
+from .browser_context import BrowserContext
+from .pagable import PagableTarget
+from .page import Page
+from .target import CDPConnection, Target, cdp_host, cdp_target_path, ws_origin
+
+
+class Browser[T: Page](Target, PagableTarget[T]):
+    """The browser endpoint.
+
+    Connects to the browser-level websocket, discovers page targets and exposes
+    them as :class:`Page` objects -- each on its own websocket
+    (``{host}/devtools/page/{id}``), with the host kept in the :data:`cdp_host`
+    context variable.  Pages are grouped into :class:`BrowserContext` profiles;
+    the default context holds pages created without an explicit one.
+
+    Generic over the page class: ``page_class`` drives ``T``, so
+    ``browser.pages``, ``new_page()`` and contexts are typed to the page type
+    you pass (e.g. ``Browser.connect_http(url, page_class=Page[RequestListener])``).
+    """
+
+    #: Page class captured from ``Browser[Page[...]]`` subscription, used by
+    #: :meth:`get_distant_browser` so the feature set is derived automatically.
+    _page_class_override: ClassVar[Optional[type]] = None
+
+    def __class_getitem__(cls, item):
+        """``Browser[Page[Feat]]`` -> a real subclass remembering that page class.
+
+        A bare type parameter (``Browser[P]`` inside generic code) falls back to
+        the normal typing machinery.
+        """
+        if isinstance(item, type) and issubclass(item, Page):
+            name = f"{cls.__name__}[{item.__name__}]"
+            return type(name, (cls,), {"_page_class_override": item})
+        return super().__class_getitem__(item)  # type: ignore[misc]
+
+    def __init__(
+        self,
+        target_info: TargetDomain.TargetInfo,
+        *,
+        page_class: type[T] = Page,
+    ):
+        Target.__init__(self, target_info, None)
+        PagableTarget.__init__(self)
+        self.page_class: type[T] = page_class
+        self._contexts: dict[Optional[str], BrowserContext[T]] = {}
+        self.default_context: BrowserContext[T] | None = None
+
+    @property
+    def contexts(self):
+        return list(self._contexts.values())
+
+    @property
+    def _scope_context_id(self) -> Optional[str]:
+        return None
+
+    @classmethod
+    async def connect_http[P: Page = Page](
+        cls,
+        endpoint: str = "http://127.0.0.1:9222",
+        *,
+        page_class: type[P] = Page,
+    ) -> "Browser[P]":
+        """Discover the websocket via ``/json/version`` then connect.
+
+        Binds :data:`cdp_host` to the endpoint's origin so every page connected
+        afterwards reaches the browser at the same host without it being passed
+        around.
+        """
+        with urllib.request.urlopen(f"{endpoint.rstrip('/')}/json/version") as resp:
+            info = json.loads(resp.read())
+        ws_url = info["webSocketDebuggerUrl"]
+        cdp_host.set(ws_origin(ws_url))
+
+        boot = CDPConnection()
+        await boot._open(ws_url)
+        try:
+            browser_info = (await CDP(boot).Target.get_target_info()).target_info
+        finally:
+            await boot.close()
+
+        browser = Browser[P](browser_info, page_class=page_class)
+        await browser.connect(ws_url)
+        await browser._discover()
+        return browser
+
+    @classmethod
+    async def get_distant_browser(
+        cls,
+        server: str = "http://127.0.0.1:9333",
+        *,
+        features: Optional[tuple] = None,
+        page_class: Optional[type] = None,
+        **launch,
+    ) -> "Browser[T]":
+        """Create a browser on a parsek-cdp-server and return it, connected.
+
+        ``Browser[Page[RequestListener]].get_distant_browser("http://host:9333",
+        headless=True)`` issues ``POST /browsers?feature=RequestListener`` with the
+        launch settings (``headless``, ``executable``, ``extra_args``, ...) in the
+        body, then connects to the proxy's control channel.  The returned browser
+        drives the *remote* browser exactly like a local one -- pages connect to
+        the proxy's per-target endpoints and the named features are aggregated
+        server-side.
+
+        The feature set defaults to the ones declared on the subscripted page
+        class (``Page[RequestListener]`` -> ``RequestListener``); pass ``features``
+        to override.
+        """
+        resolved_page = page_class or cls._page_class_override or Page
+        feats = (
+            features
+            if features is not None
+            else getattr(resolved_page, "_feature_classes", ())
+        )
+        query = "&".join(f"feature={urllib.parse.quote(f.__name__)}" for f in feats)
+        url = f"{server.rstrip('/')}/browsers" + (f"?{query}" if query else "")
+        payload = json.dumps(launch).encode()
+        # Run the blocking HTTP POST off the event loop so it never stalls it
+        # (notably when client and server share one loop in tests).
+        info = await asyncio.to_thread(cls._post_json, url, payload)
+
+        control_url = info["wsUrl"]
+        suffix = "/control"
+        ws_base = (
+            control_url[: -len(suffix)] if control_url.endswith(suffix) else control_url
+        )
+        cdp_host.set(ws_base)
+        cdp_target_path.set("/page/")
+
+        boot = CDPConnection()
+        await boot._open(control_url)
+        try:
+            browser_info = (await CDP(boot).Target.get_target_info()).target_info
+        finally:
+            await boot.close()
+
+        # Pages on a remote browser run their features as *clients* (consuming the
+        # server-aggregated ``Parsek.*`` events), not "local" (which would digest
+        # raw CDP -- exactly what the server already suppresses).
+        remote_page = type(
+            resolved_page.__name__,
+            (resolved_page,),
+            {"_feature_role": "client"},
+        )
+        browser = cls(browser_info, page_class=remote_page)
+        await browser.connect(control_url)
+        await browser._discover()
+        return browser
+
+    @staticmethod
+    def _post_json(url: str, payload: bytes) -> dict:
+        request = urllib.request.Request(
+            url,
+            data=payload,
+            method="POST",
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(request) as resp:
+            return json.loads(resp.read())
+
+    async def _discover(self) -> None:
+        """Populate contexts and pages from the live browser (after connect)."""
+        contexts = await self.cdp.Target.get_browser_contexts()
+        for context_id in contexts.browser_context_ids:
+            self._contexts[context_id] = BrowserContext(self, context_id)
+        for target in self.targets:
+            target_data = target._target
+            if target_data.type_ not in ("page", "tab"):
+                continue
+            page = await self._ensure_page(target_data)
+            self._pages[target.id] = page
+            if target_data.browser_context_id not in self._contexts:
+                context = BrowserContext(self, target_data.browser_context_id)
+                self._contexts[target_data.browser_context_id] = context
+                self.default_context = context
+            self._contexts[target_data.browser_context_id]._pages[target.id] = page
+
+    async def connect(self, url: Optional[str] = None) -> "Browser[T]":
+        """Connect the browser websocket and start watching for page targets.
+
+        The browser endpoint's ws path id does not match its ``target_id``, so
+        :meth:`connect_http` passes the discovered ``webSocketDebuggerUrl`` as
+        ``url``.  Generic target tracking is wired by :meth:`Target.connect`; the
+        page-specific discovery handling lives in :class:`PagableTarget` and is
+        registered here on the browser's own connection.
+        """
+        await super().connect(url)
+        await self.cdp.Target.set_discover_targets(discover=True)
+        await self.refresh_targets()
+        self.watch(self)
+        return self
+
+    async def create_context(
+        self,
+        *,
+        dispose_on_detach: Optional[bool] = None,
+        proxy_server: Optional[str] = None,
+        proxy_bypass_list: Optional[str] = None,
+    ):
+        """Create a fresh, isolated browser context (incognito-like)."""
+        result = await self.cdp.Target.create_browser_context(
+            dispose_on_detach=dispose_on_detach,
+            proxy_server=proxy_server,
+            proxy_bypass_list=proxy_bypass_list,
+        )
+        ctx = BrowserContext[T](self, result.browser_context_id)
+        self._contexts[ctx.id] = ctx
+        return ctx
+
+    async def fetch_contexts(self) -> List[BrowserContext]:
+        """Sync :attr:`contexts` with the browser and return them all."""
+        result = await self.cdp.Target.get_browser_contexts()
+        for cid in result.browser_context_ids:
+            self._contexts.setdefault(cid, BrowserContext(self, cid))
+        return list(self._contexts.values())
+
+    def _context_for(self, context_id: Optional[str]) -> BrowserContext[T]:
+        ctx = self._contexts.get(context_id)
+        if ctx is None:
+            ctx = BrowserContext(self, context_id)
+            self._contexts[context_id] = ctx
+        return ctx
+
+    def _forget_context(self, context_id: str) -> None:
+        ctx = self._contexts.pop(context_id, None)
+        if ctx is not None:
+            for target_id in list(ctx._pages):
+                self._drop_page(target_id)