chromedeveloperprotocol-client 0.1.0__py3-none-any.whl

cdp/protocol/web_authn/methods/service.py

@@ -0,0 +1,164 @@
+"""CDP WebAuthn Domain Methods"""
+from ..types import *
+from .types import *
+from typing import Optional, Dict, Any, Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ....service import Client
+
+class WebAuthnMethods:
+    """
+    Methods for the WebAuthn domain.
+    """
+    def __init__(self, client: "Client"):
+        """
+        Initialize the WebAuthn methods.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        """
+        self.client = client
+
+    async def enable(self, params: Optional[enableParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Enable the WebAuthn domain and start intercepting credential storage and retrieval with a virtual authenticator.    
+        Args:
+            params (enableParameters, optional): Parameters for the enable method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the enable call.
+        """
+        return await self.client.send(method="WebAuthn.enable", params=params,session_id=session_id)
+    async def disable(self, params: None=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Disable the WebAuthn domain.    
+        Args:
+            params (None, optional): Parameters for the disable method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the disable call.
+        """
+        return await self.client.send(method="WebAuthn.disable", params=params,session_id=session_id)
+    async def add_virtual_authenticator(self, params: Optional[addVirtualAuthenticatorParameters]=None,session_id: Optional[str] = None) -> addVirtualAuthenticatorReturns:
+        """
+    Creates and adds a virtual authenticator.    
+        Args:
+            params (addVirtualAuthenticatorParameters, optional): Parameters for the addVirtualAuthenticator method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    addVirtualAuthenticatorReturns: The result of the addVirtualAuthenticator call.
+        """
+        return await self.client.send(method="WebAuthn.addVirtualAuthenticator", params=params,session_id=session_id)
+    async def set_response_override_bits(self, params: Optional[setResponseOverrideBitsParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Resets parameters isBogusSignature, isBadUV, isBadUP to false if they are not present.    
+        Args:
+            params (setResponseOverrideBitsParameters, optional): Parameters for the setResponseOverrideBits method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the setResponseOverrideBits call.
+        """
+        return await self.client.send(method="WebAuthn.setResponseOverrideBits", params=params,session_id=session_id)
+    async def remove_virtual_authenticator(self, params: Optional[removeVirtualAuthenticatorParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Removes the given authenticator.    
+        Args:
+            params (removeVirtualAuthenticatorParameters, optional): Parameters for the removeVirtualAuthenticator method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the removeVirtualAuthenticator call.
+        """
+        return await self.client.send(method="WebAuthn.removeVirtualAuthenticator", params=params,session_id=session_id)
+    async def add_credential(self, params: Optional[addCredentialParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Adds the credential to the specified authenticator.    
+        Args:
+            params (addCredentialParameters, optional): Parameters for the addCredential method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the addCredential call.
+        """
+        return await self.client.send(method="WebAuthn.addCredential", params=params,session_id=session_id)
+    async def get_credential(self, params: Optional[getCredentialParameters]=None,session_id: Optional[str] = None) -> getCredentialReturns:
+        """
+    Returns a single credential stored in the given virtual authenticator that matches the credential ID.    
+        Args:
+            params (getCredentialParameters, optional): Parameters for the getCredential method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    getCredentialReturns: The result of the getCredential call.
+        """
+        return await self.client.send(method="WebAuthn.getCredential", params=params,session_id=session_id)
+    async def get_credentials(self, params: Optional[getCredentialsParameters]=None,session_id: Optional[str] = None) -> getCredentialsReturns:
+        """
+    Returns all the credentials stored in the given virtual authenticator.    
+        Args:
+            params (getCredentialsParameters, optional): Parameters for the getCredentials method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    getCredentialsReturns: The result of the getCredentials call.
+        """
+        return await self.client.send(method="WebAuthn.getCredentials", params=params,session_id=session_id)
+    async def remove_credential(self, params: Optional[removeCredentialParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Removes a credential from the authenticator.    
+        Args:
+            params (removeCredentialParameters, optional): Parameters for the removeCredential method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the removeCredential call.
+        """
+        return await self.client.send(method="WebAuthn.removeCredential", params=params,session_id=session_id)
+    async def clear_credentials(self, params: Optional[clearCredentialsParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Clears all the credentials from the specified device.    
+        Args:
+            params (clearCredentialsParameters, optional): Parameters for the clearCredentials method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the clearCredentials call.
+        """
+        return await self.client.send(method="WebAuthn.clearCredentials", params=params,session_id=session_id)
+    async def set_user_verified(self, params: Optional[setUserVerifiedParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Sets whether User Verification succeeds or fails for an authenticator. The default is true.    
+        Args:
+            params (setUserVerifiedParameters, optional): Parameters for the setUserVerified method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the setUserVerified call.
+        """
+        return await self.client.send(method="WebAuthn.setUserVerified", params=params,session_id=session_id)
+    async def set_automatic_presence_simulation(self, params: Optional[setAutomaticPresenceSimulationParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Sets whether tests of user presence will succeed immediately (if true) or fail to resolve (if false) for an authenticator. The default is true.    
+        Args:
+            params (setAutomaticPresenceSimulationParameters, optional): Parameters for the setAutomaticPresenceSimulation method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the setAutomaticPresenceSimulation call.
+        """
+        return await self.client.send(method="WebAuthn.setAutomaticPresenceSimulation", params=params,session_id=session_id)
+    async def set_credential_properties(self, params: Optional[setCredentialPropertiesParameters]=None,session_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+    Allows setting credential properties. https://w3c.github.io/webauthn/#sctn-automation-set-credential-properties    
+        Args:
+            params (setCredentialPropertiesParameters, optional): Parameters for the setCredentialProperties method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+    Dict[str, Any]: The result of the setCredentialProperties call.
+        """
+        return await self.client.send(method="WebAuthn.setCredentialProperties", params=params,session_id=session_id)

cdp/protocol/web_authn/methods/types.py

@@ -0,0 +1,61 @@
+"""CDP WebAuthn Methods Types"""
+
+from typing import TypedDict, NotRequired, Required, Literal, Any, Dict, Union, Optional, List, Set, Tuple
+
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from cdp.protocol.web_authn.types import AuthenticatorId
+    from cdp.protocol.web_authn.types import Credential
+    from cdp.protocol.web_authn.types import VirtualAuthenticatorOptions
+
+class enableParameters(TypedDict, total=False):
+    enableUI: NotRequired['bool']
+    """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."""
+
+class addVirtualAuthenticatorParameters(TypedDict, total=True):
+    options: 'VirtualAuthenticatorOptions'
+class setResponseOverrideBitsParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    isBogusSignature: NotRequired['bool']
+    """If isBogusSignature is set, overrides the signature in the authenticator response to be zero. Defaults to false."""
+    isBadUV: NotRequired['bool']
+    """If isBadUV is set, overrides the UV bit in the flags in the authenticator response to be zero. Defaults to false."""
+    isBadUP: NotRequired['bool']
+    """If isBadUP is set, overrides the UP bit in the flags in the authenticator response to be zero. Defaults to false."""
+class removeVirtualAuthenticatorParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+class addCredentialParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    credential: 'Credential'
+class getCredentialParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    credentialId: 'str'
+class getCredentialsParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+class removeCredentialParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    credentialId: 'str'
+class clearCredentialsParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+class setUserVerifiedParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    isUserVerified: 'bool'
+class setAutomaticPresenceSimulationParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    enabled: 'bool'
+class setCredentialPropertiesParameters(TypedDict, total=True):
+    authenticatorId: 'AuthenticatorId'
+    credentialId: 'str'
+    backupEligibility: NotRequired['bool']
+    backupState: NotRequired['bool']
+
+
+class addVirtualAuthenticatorReturns(TypedDict):
+    authenticatorId: 'AuthenticatorId'
+
+
+
+class getCredentialReturns(TypedDict):
+    credential: 'Credential'
+class getCredentialsReturns(TypedDict):
+    credentials: 'List[Credential]'

cdp/protocol/web_authn/service.py

@@ -0,0 +1,21 @@
+"""CDP WebAuthn Domain"""
+from typing import TYPE_CHECKING
+from .methods.service import WebAuthnMethods
+from .events.service import WebAuthnEvents
+
+if TYPE_CHECKING:
+    from ...service import Client
+
+class WebAuthn(WebAuthnMethods, WebAuthnEvents):
+    """
+    This domain allows configuring virtual authenticators to test the WebAuthn API.
+    """
+    def __init__(self, client: "Client"):
+        """
+        Initialize the WebAuthn domain.
+        
+        Args:
+            client ("Client"): The parent CDP client instance.
+        """
+        WebAuthnMethods.__init__(self, client)
+        WebAuthnEvents.__init__(self, client)

cdp/protocol/web_authn/types.py

@@ -0,0 +1,54 @@
+"""CDP WebAuthn Types"""
+
+from typing import TypedDict, NotRequired, Required, Literal, Any, Dict, Union, Optional, List, Set, Tuple
+
+AuthenticatorId = str
+AuthenticatorProtocol = Literal['u2f','ctap2']
+Ctap2Version = Literal['ctap2_0','ctap2_1']
+AuthenticatorTransport = Literal['usb','nfc','ble','cable','internal']
+class VirtualAuthenticatorOptions(TypedDict, total=True):
+    protocol: 'AuthenticatorProtocol'
+    transport: 'AuthenticatorTransport'
+    ctap2Version: NotRequired['Ctap2Version']
+    """Defaults to ctap2_0. Ignored if |protocol| == u2f."""
+    hasResidentKey: NotRequired['bool']
+    """Defaults to false."""
+    hasUserVerification: NotRequired['bool']
+    """Defaults to false."""
+    hasLargeBlob: NotRequired['bool']
+    """If set to true, the authenticator will support the largeBlob extension. https://w3c.github.io/webauthn#largeBlob Defaults to false."""
+    hasCredBlob: NotRequired['bool']
+    """If set to true, the authenticator will support the credBlob extension. https://fidoalliance.org/specs/fido-v2.1-rd-20201208/fido-client-to-authenticator-protocol-v2.1-rd-20201208.html#sctn-credBlob-extension Defaults to false."""
+    hasMinPinLength: NotRequired['bool']
+    """If set to true, the authenticator will support the minPinLength extension. https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html#sctn-minpinlength-extension Defaults to false."""
+    hasPrf: NotRequired['bool']
+    """If set to true, the authenticator will support the prf extension. https://w3c.github.io/webauthn/#prf-extension Defaults to false."""
+    automaticPresenceSimulation: NotRequired['bool']
+    """If set to true, tests of user presence will succeed immediately. Otherwise, they will not be resolved. Defaults to true."""
+    isUserVerified: NotRequired['bool']
+    """Sets whether User Verification succeeds or fails for an authenticator. Defaults to false."""
+    defaultBackupEligibility: NotRequired['bool']
+    """Credentials created by this authenticator will have the backup eligibility (BE) flag set to this value. Defaults to false. https://w3c.github.io/webauthn/#sctn-credential-backup"""
+    defaultBackupState: NotRequired['bool']
+    """Credentials created by this authenticator will have the backup state (BS) flag set to this value. Defaults to false. https://w3c.github.io/webauthn/#sctn-credential-backup"""
+class Credential(TypedDict, total=True):
+    credentialId: 'str'
+    isResidentCredential: 'bool'
+    privateKey: 'str'
+    """The ECDSA P-256 private key in PKCS#8 format. (Encoded as a base64 string when passed over JSON)"""
+    signCount: 'int'
+    """Signature counter. This is incremented by one for each successful assertion. See https://w3c.github.io/webauthn/#signature-counter"""
+    rpId: NotRequired['str']
+    """Relying Party ID the credential is scoped to. Must be set when adding a credential."""
+    userHandle: NotRequired['str']
+    """An opaque byte sequence with a maximum size of 64 bytes mapping the credential to a specific user. (Encoded as a base64 string when passed over JSON)"""
+    largeBlob: NotRequired['str']
+    """The large blob associated with the credential. See https://w3c.github.io/webauthn/#sctn-large-blob-extension (Encoded as a base64 string when passed over JSON)"""
+    backupEligibility: NotRequired['bool']
+    """Assertions returned by this credential will have the backup eligibility (BE) flag set to this value. Defaults to the authenticator's defaultBackupEligibility value."""
+    backupState: NotRequired['bool']
+    """Assertions returned by this credential will have the backup state (BS) flag set to this value. Defaults to the authenticator's defaultBackupState value."""
+    userName: NotRequired['str']
+    """The credential's user.name property. Equivalent to empty if not set. https://w3c.github.io/webauthn/#dom-publickeycredentialentity-name"""
+    userDisplayName: NotRequired['str']
+    """The credential's user.displayName property. Equivalent to empty if not set. https://w3c.github.io/webauthn/#dom-publickeycredentialuserentity-displayname"""

cdp/service.py

@@ -0,0 +1,184 @@
+from typing import Optional, Dict, Any, Callable,Annotated, List
+from operator import add
+import websockets
+import asyncio
+import logging
+import json
+
+from .domains import Domains
+from .generator.service import CDPGenerator
+
+class Client(Domains):
+    """
+    Core client for interacting with Chrome DevTools Protocol (CDP).
+    
+    This class provides a high-level API to send commands and listen for events across
+    various CDP domains. It manages the underlying WebSocket connection and dispatches
+    messages to the appropriate handlers.
+    
+    Attributes:
+        url (str): The WebSocket URL of the remote debugging target.
+        ws (websockets.ClientConnection): The active WebSocket connection.
+        listen_task (asyncio.Task): Background task processing incoming CDP messages.
+        id_counter (int): Counter for generating unique request IDs.
+        pending_requests (Dict[int, asyncio.Future]): Tracks outstanding requests by ID.
+        event_handlers (Dict[str, List[Callable]]): Registered callbacks for CDP events.
+    """
+    def __init__(self, url: str, refresh: bool = False):
+        """
+        Initialize the CDP Client.
+        
+        Args:
+            url (str): WebSocket debugger URL.
+            refresh (bool): If True, regenerates the CDP protocol definitions on initialization.
+        """
+        super().__init__(self)
+        self.url = url
+        self.ws :Optional[websockets.ClientConnection] = None
+        self.listen_task :Optional[asyncio.Task] = None
+        self.id_counter: Annotated[int, add] = 0
+        self.pending_requests: Dict[int, asyncio.Future] = {}
+        self.event_handlers: Dict[str, List[Callable[[Any, Optional[str]], None]]] = {}
+        
+        if refresh:
+            self.refresh()
+
+    async def __aenter__(self):
+        """Connect to the WebSocket and start the background listener."""
+        self.ws = await websockets.connect(self.url,max_size=100*1024*1024)
+        self.listen_task = asyncio.create_task(self.listen())
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Cancel the listener, clear pending requests, and close the WebSocket."""
+        for future in self.pending_requests.values():
+            if not future.done():
+                future.set_exception(Exception("WebSocket connection closed"))
+        self.pending_requests.clear()
+        if self.listen_task:
+            try:
+                self.listen_task.cancel()
+                await self.listen_task
+            except asyncio.CancelledError:
+                pass
+            finally:
+                self.listen_task = None
+        if self.ws:
+            await self.ws.close()
+            self.ws = None
+
+    async def send(self, method: str, params: Optional[dict] = None,session_id: Optional[str] = None) -> Any:
+        """
+        Send a CDP command and wait for the result.
+        
+        Args:
+            method (str): The CDP method name (e.g., 'Page.navigate').
+            params (dict, optional): Parameters for the method.
+            session_id (str, optional): Target session ID for flat protocol usage.
+            
+        Returns:
+            Any: The 'result' object from the CDP response.
+            
+        Raises:
+            Exception: If the CDP returns an error or the connection is lost.
+        """
+        self.id_counter+=1
+        future = asyncio.Future()
+        self.pending_requests[self.id_counter] = future
+        
+        try:
+            message = {"id": self.id_counter, "method": method, "params": params or {}}
+            if session_id:
+                message['sessionId'] = session_id
+            await self.ws.send(json.dumps(message))
+            return await future
+        except Exception as e:
+            self.pending_requests.pop(self.id_counter, None)
+            raise e
+
+    def on(self, event: str, callback: Callable[[Any, Optional[str]], None]) -> None:
+        """
+        Register an event handler. Alias for `Client.register`.
+        
+        Args:
+            event (str): The CDP event name (e.g., 'Page.loadEventFired').
+            callback (callable): Function called with (params, session_id).
+        """
+        self.register(event, callback)
+
+    def register(self, event: str, callback: Callable[[Any, Optional[str]], None]) -> None:
+        """
+        Register a handler for a specific CDP event.
+        
+        Args:
+            event (str): The CDP event name.
+            callback (callable): Function called with (params, session_id).
+        """
+        if event not in self.event_handlers:
+            self.event_handlers[event] = []
+        self.event_handlers[event].append(callback)
+
+    def unregister(self, event: str) -> None:
+        """
+        Unregister all handlers for a specific CDP event.
+        
+        Args:
+            event (str): The CDP event name.
+        """
+        if event in self.event_handlers:
+            del self.event_handlers[event]
+    
+    def refresh(self):
+        """
+        Refresh the CDP protocol definitions by fetching latest schemas and 
+        regenerating the client source code on disk.
+        """
+        generator = CDPGenerator()
+        generator.generate()
+
+    async def listen(self):
+        """
+        Internal background loop that receives messages from the WebSocket.
+        Dispatches responses to pending request futures and events to registered handlers.
+        """
+        while True:
+            try:
+                message = await self.ws.recv()
+                data = json.loads(message)
+                if "id" in data:
+                    # Method
+                    request_id=data["id"]
+                    logging.debug(f"Received method response: {data}")
+                    if request_id not in self.pending_requests:
+                        continue
+                    future = self.pending_requests.pop(request_id)
+                    if not future.done():
+                        if "error" in data:
+                            future.set_exception(Exception(data.get("error")))
+                        else:
+                            future.set_result(data.get("result"))
+                elif 'method' in data:
+                    # Event
+                    method=data.get("method")
+                    params = data.get("params", {})
+                    session_id=data.get("sessionId")
+                    logging.debug(f"Received event: {data}")
+                    if method not in self.event_handlers:
+                        continue
+                    
+                    handlers = self.event_handlers[method]
+                    for handler in handlers:
+                        try:
+                            if asyncio.iscoroutinefunction(handler):
+                                asyncio.create_task(handler(params,session_id))
+                            else:
+                                handler(params,session_id)
+                        except Exception as e:
+                            logging.error(f"Error in event handler for {method}: {e}")
+                            continue
+            except websockets.exceptions.ConnectionClosed:
+                logging.info("CDP WebSocket connection closed")
+                break
+            except Exception as e:
+                logging.error(f"Error in CDP listen loop: {e}")
+                break

chromedeveloperprotocol_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: chromedeveloperprotocol-client
+Version: 0.1.0
+Summary: Python wrapper for Chrome DevTools Protocol
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: inflection>=0.5.1
+Requires-Dist: ipykernel>=7.1.0
+Requires-Dist: jinja2-strcase>=0.0.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: websockets>=15.0.1
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest>=8.0.0; extra == 'test'