stagehand 4.3.0a0.dev1620__tar.gz → 4.3.0a0.dev1624__tar.gz

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.3.0a0.dev1620
+Version: 4.3.0a0.dev1624
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,agent,ai-agent,browser,browser-agent,browser-automation,computer-use,headless,playwright,cdp,llm,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stagehand"
-version = "4.3.0a0.dev1620"
+version = "4.3.0a0.dev1624"
 description = "Browserbase's SDK for building browser agents"
 readme = "README.md"
 requires-python = ">=3.11"

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/_extension/service-worker.js

@@ -7363,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "3.0.0-alpha-76cd7e0f2ff04b0fb5c07e27e0db70746d0ad3c8",
+	version: "3.0.0-alpha-77170ed9f8252581458360ab511c55a4be31fb44",
 	"private": true,
 	type: "module",
 	exports: {
@@ -12527,8 +12527,20 @@ strictObject({
 	acceptDownloads: boolean().optional(),
 	keepAlive: boolean().optional()
 }).meta({ id: "LocalBrowserLaunchOptions" });
+var CDPHeadersSchema = preprocess((value) => {
+	try {
+		if (typeof value !== "object" || value === null || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) return null;
+		const entries = Object.entries(value);
+		if (!entries.every(([name, content]) => name.length > 0 && !/[^!#$%&'*+\-.^_`|~0-9A-Za-z]/.test(name) && typeof content === "string" && !/[^\t\x20-\x7e]/.test(content) && content === content.replace(/^[ \t]+|[ \t]+$/g, ""))) return null;
+		return Object.fromEntries(entries);
+	} catch {
+		return null;
+	}
+}, record(string(), string(), { error: "headers must map valid HTTP header names to ASCII string values without leading or trailing spaces or tabs" }));
 strictObject({
 	cdpUrl: string().min(1),
+	/** Headers for client-side CDP discovery and WebSocket connections. */
+	headers: CDPHeadersSchema.optional(),
 	extensionId: string().optional(),
 	/**
 	* Browser-level CDP WebSocket URL dialed by the extension inside Chrome.
@@ -54471,7 +54483,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.2.0-alpha-76cd7e0f2ff04b0fb5c07e27e0db70746d0ad3c8",
+	version: "1.2.0-alpha-77170ed9f8252581458360ab511c55a4be31fb44",
 	"private": true,
 	type: "module",
 	scripts: {

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/_generated/protocol_version.py

@@ -1,4 +1,4 @@
 """Generated from packages/protocol/package.json. Do not edit."""
 
 PROTOCOL_SEMVER_PATTERN = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$'
-STAGEHAND_PROTOCOL_VERSION = '3.0.0-alpha-76cd7e0f2ff04b0fb5c07e27e0db70746d0ad3c8'
+STAGEHAND_PROTOCOL_VERSION = '3.0.0-alpha-77170ed9f8252581458360ab511c55a4be31fb44'

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/_validation.py

@@ -1,8 +1,19 @@
+import re
 from collections.abc import Mapping
-from typing import Annotated
+from typing import Annotated, cast
 from urllib.parse import urlparse
 
-from pydantic import AfterValidator, AnyUrl, BaseModel, ConfigDict, TypeAdapter, model_validator
+from pydantic import (
+    AfterValidator,
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    TypeAdapter,
+    ValidationError,
+    ValidatorFunctionWrapHandler,
+    WrapValidator,
+    model_validator,
+)
 from typing_extensions import override
 
 _url_adapter = TypeAdapter(AnyUrl)
@@ -15,6 +26,54 @@ def _validate_url(value: str) -> str:
 
 WireUrl = Annotated[str, AfterValidator(_validate_url)]
 
+# RFC 9110 field names are tokens. Restrict values to ASCII so HTTP discovery
+# and WebSocket handshakes encode them identically; allow only internal whitespace.
+_HEADER_NAME = re.compile(r"[!#$%&'*+\-.^_`|~0-9A-Za-z]+")
+_HEADER_VALUE = re.compile(r"[\t\x20-\x7e]*")
+
+
+def _validate_headers(value: Mapping[str, str]) -> Mapping[str, str]:
+    for name, header_value in value.items():
+        if not _HEADER_NAME.fullmatch(name):
+            raise ValueError
+        if not _HEADER_VALUE.fullmatch(header_value) or header_value != header_value.strip(" \t"):
+            raise ValueError
+    return value
+
+
+def _redact_header_validation_errors(
+    value: object, handler: ValidatorFunctionWrapHandler
+) -> dict[str, str]:
+    try:
+        return cast(dict[str, str], handler(value))
+    except ValidationError:
+        # Error inputs, locations, and validator context can all contain credentials.
+        # Rebuild the error rather than only hiding inputs in its formatted message.
+        raise ValidationError.from_exception_data(
+            "CDP headers",
+            [
+                {
+                    "type": "value_error",
+                    "loc": (),
+                    "input": "[redacted]",
+                    "ctx": {
+                        "error": ValueError(
+                            "headers must map valid HTTP header names to ASCII string values "
+                            "without leading or trailing spaces or tabs"
+                        )
+                    },
+                }
+            ],
+            hide_input=True,
+        ) from None
+
+
+WireHeaders = Annotated[
+    dict[str, str],
+    AfterValidator(_validate_headers),
+    WrapValidator(_redact_header_validation_errors),
+]
+
 
 def _validate_websocket_url(value: str) -> str:
     parsed = urlparse(value)

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/browser.py

@@ -312,12 +312,14 @@ async def _connect_browser(
     preloaded_extension: bool = False,
     after_connect: Callable[[CDPClient], Awaitable[None]] | None = None,
     worker_init_metadata: _WorkerInitMetadata,
+    headers: Mapping[str, str] | None = None,
 ) -> StagehandBrowser:
     owns_source = origin == "launched" and not source.keep_alive
     cdp_client: CDPClient | None = None
     try:
         cdp_client = await CDPClient.connect(
             cdp_url=source.cdp_url,
+            **({"headers": headers} if headers else {}),
             extension_dir=extension_dir,
             local_extension_dir=local_extension_dir,
             extension_id=extension_id,
@@ -536,6 +538,7 @@ class LocalBrowser:
         cdp_url: str,
         extension_id: str | None = None,
         extension_cdp_url: str | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> StagehandBrowser:
         """Connect to an existing browser.
 
@@ -547,6 +550,10 @@ class LocalBrowser:
                 client connected to. Set it when the client reaches Chrome through
                 a proxy the browser cannot or should not use, such as an
                 authenticated gateway whose URL carries credentials.
+            headers: HTTP headers to send with the CDP connection, such as a
+                gateway's credentials, so they need not ride in `cdp_url`. They
+                go to `cdp_url` and to the WebSocket it advertises when that is
+                on the same host, never elsewhere, and never to the extension.
         """
         options = LocalBrowserConnectOptions.model_validate({
             name: value
@@ -554,6 +561,7 @@ class LocalBrowser:
                 ("cdp_url", cdp_url),
                 ("extension_id", extension_id),
                 ("extension_cdp_url", extension_cdp_url),
+                ("headers", dict(headers) if isinstance(headers, Mapping) else headers),
             )
             if value is not None
         })
@@ -567,6 +575,7 @@ class LocalBrowser:
                 browser=None,
                 browser_cdp_url=options.extension_cdp_url,
             ),
+            headers=options.headers,
         )
 
 

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/cdp_client.py

@@ -2,19 +2,28 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import re
 import time
 from collections.abc import Callable, Mapping
 from contextlib import suppress
 from dataclasses import dataclass
 from typing import Any, Literal, Protocol, cast
-from urllib.request import urlopen
+from urllib.error import HTTPError
+from urllib.parse import urljoin, urlsplit
+from urllib.request import HTTPRedirectHandler, Request, build_opener, urlopen
+
+from typing_extensions import override
+from websockets.asyncio.client import connect as WebSocketConnect
+from websockets.exceptions import InvalidStatus
 
 from stagehand._generated.protocol_version import (
     PROTOCOL_SEMVER_PATTERN,
     STAGEHAND_PROTOCOL_VERSION,
 )
 
+_LOGGER = logging.getLogger(__name__)
+
 STAGEHAND_SEND_TO_HOST_BINDING = "__stagehandSendToHost"
 _RUNTIME_NAME = "stagehand"
 _STAGEHAND_EXTENSION_NAME = "Stagehand Runtime"
@@ -257,6 +266,7 @@ class CDPClient:
         extension_id: str | None = None,
         preloaded_extension: bool = False,
         service_worker_url_includes: str | None = None,
+        headers: Mapping[str, str] | None = None,
     ) -> CDPClient:
         """Connect without an independent lifecycle deadline.
 
@@ -278,8 +288,16 @@ class CDPClient:
                 "or preloaded_extension is required"
             )
 
-        web_socket_debugger_url = await _resolve_browser_web_socket_url(cdp_url)
-        socket = await _connect_web_socket(web_socket_debugger_url)
+        web_socket_debugger_url = await _resolve_browser_web_socket_url(cdp_url, headers=headers)
+        web_socket_headers = headers or None
+        if web_socket_headers and not _can_forward_headers(cdp_url, web_socket_debugger_url):
+            web_socket_headers = None
+            _LOGGER.debug(
+                "CDP headers were withheld from the advertised WebSocket endpoint because "
+                "its host or port differs, or forwarding would downgrade transport security. "
+                "If the handshake is rejected, check the gateway's advertised CDP endpoint."
+            )
+        socket = await _connect_web_socket(web_socket_debugger_url, headers=web_socket_headers)
         client = cls(socket, web_socket_debugger_url)
 
         try:
@@ -659,33 +677,103 @@ class CDPClient:
         task.add_done_callback(finish)
 
 
-async def _connect_web_socket(url: str) -> _WebSocket:
-    from websockets.asyncio.client import connect
+class _UnsafeCDPRedirectError(RuntimeError):
+    """A redirect would expose caller headers to an unauthorized endpoint."""
+
+
+_DEFAULT_PORTS = {"http": 80, "ws": 80, "https": 443, "wss": 443}
+
+
+def _can_forward_headers(source: str, destination: str) -> bool:
+    """Require the same host and effective port, without a TLS downgrade."""
+    try:
+        first, second = urlsplit(source), urlsplit(destination)
+        return (
+            first.scheme in _DEFAULT_PORTS
+            and second.scheme in _DEFAULT_PORTS
+            and first.hostname is not None
+            and first.hostname == second.hostname
+            and (first.port if first.port is not None else _DEFAULT_PORTS[first.scheme])
+            == (second.port if second.port is not None else _DEFAULT_PORTS[second.scheme])
+            and not (first.scheme in ("https", "wss") and second.scheme in ("http", "ws"))
+        )
+    except ValueError:
+        return False
+
+
+class _CDPRedirectHandler(HTTPRedirectHandler):
+    @override
+    def redirect_request(
+        self, req: Request, fp: Any, code: int, msg: str, headers: Any, newurl: str
+    ) -> Request | None:
+        if not _can_forward_headers(req.full_url, newurl):
+            raise _UnsafeCDPRedirectError(
+                "Refusing CDP HTTP redirect with headers to a different host or port, "
+                "or an insecure endpoint"
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+class _CDPWebSocketConnect(WebSocketConnect):
+    @override
+    def process_redirect(self, exc: Exception) -> Exception | str:
+        if (
+            self.additional_headers
+            and isinstance(exc, InvalidStatus)
+            and exc.response.status_code in (300, 301, 302, 303, 307, 308)
+            and "Location" in exc.response.headers
+            and not _can_forward_headers(
+                self.uri, urljoin(self.uri, exc.response.headers["Location"])
+            )
+        ):
+            return _UnsafeCDPRedirectError(
+                "Refusing CDP WebSocket redirect with headers to a different host or port, "
+                "or an insecure endpoint"
+            )
+        return super().process_redirect(exc)
+
 
+async def _connect_web_socket(url: str, *, headers: Mapping[str, str] | None = None) -> _WebSocket:
     return cast(
         _WebSocket,
-        await connect(url, open_timeout=None, max_size=None),
+        await _CDPWebSocketConnect(
+            url, open_timeout=None, max_size=None, additional_headers=headers
+        ),
     )
 
 
-async def _resolve_browser_web_socket_url(cdp_url: str) -> str:
+async def _resolve_browser_web_socket_url(
+    cdp_url: str, *, headers: Mapping[str, str] | None = None
+) -> str:
     if cdp_url.startswith(("ws://", "wss://")):
         return cdp_url
 
     base_url = cdp_url.rstrip("/")
     while True:
         try:
-            version = await asyncio.to_thread(_read_json, f"{base_url}/json/version")
+            version = await asyncio.to_thread(_read_json, f"{base_url}/json/version", headers)
             debugger_url = version.get("webSocketDebuggerUrl")
             if isinstance(debugger_url, str) and debugger_url:
                 return debugger_url
+        except _UnsafeCDPRedirectError:
+            raise
+        except HTTPError as error:
+            error.close()
+            if error.code in (401, 403):
+                raise RuntimeError(
+                    f"CDP discovery was rejected with HTTP {error.code}. "
+                    "Check the gateway credentials and access permissions."
+                ) from None
         except Exception:
             pass
         await asyncio.sleep(0.25)
 
 
-def _read_json(url: str) -> dict[str, object]:
-    with urlopen(url, timeout=2) as response:  # noqa: S310 -- The user selects the CDP URL.
+def _read_json(url: str, headers: Mapping[str, str] | None = None) -> dict[str, object]:
+    request = Request(url, headers=dict(headers or {}))
+    # Keep the existing redirect behavior for connections without caller headers.
+    open_url = build_opener(_CDPRedirectHandler()).open if headers else urlopen
+    with open_url(request, timeout=2) as response:
         value: Any = json.load(response)
     if not isinstance(value, dict):
         raise RuntimeError("CDP version endpoint returned invalid JSON")

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/client_models.py

@@ -18,7 +18,7 @@ from ._generated.models import (
     StagehandResultMetadata,
     TelemetryConfig,
 )
-from ._validation import WireModel, WireUrl, WireWebSocketUrl
+from ._validation import WireHeaders, WireModel, WireUrl, WireWebSocketUrl
 from .browserbase_session import DEFAULT_BROWSERBASE_URL
 from .client_types import Cache as CacheInput
 
@@ -103,13 +103,16 @@ class LocalBrowserLaunchOptions(WireModel):
 
 
 class LocalBrowserConnectOptions(WireModel):
-    model_config = ConfigDict(extra="forbid", strict=True)
+    # Headers may carry credentials, so validation errors never echo the input.
+    model_config = ConfigDict(extra="forbid", strict=True, hide_input_in_errors=True)
 
     cdp_url: Annotated[str, Field(min_length=1)]
     extension_id: str | None = None
     """Deprecated and ignored. Omit this field; Stagehand discovers the extension automatically."""
     extension_cdp_url: WireWebSocketUrl | None = None
     """Browser-level CDP WebSocket the extension dials, when it differs from `cdp_url`."""
+    headers: WireHeaders | None = None
+    """HTTP headers sent with the CDP connection, e.g. a gateway's credentials."""
 
 
 class BrowserbaseClientOptions(WireModel):

{stagehand-4.3.0a0.dev1620 → stagehand-4.3.0a0.dev1624}/src/stagehand/client_types.py

@@ -69,6 +69,8 @@ class LocalBrowserConnectOptions(TypedDict):
     """Deprecated and ignored. Omit this field; Stagehand discovers the extension automatically."""
     extension_cdp_url: NotRequired[str]
     """Browser-level CDP WebSocket the extension dials, when it differs from `cdp_url`."""
+    headers: NotRequired[dict[str, str]]
+    """HTTP headers sent with the CDP connection, e.g. a gateway's credentials."""
 
 
 class BrowserbaseClientOptions(TypedDict, total=False):