slybrowser 0.1.0__py3-none-any.whl

slybrowser/__init__.py

@@ -0,0 +1,124 @@
+"""Public Python API for SlyBrowser."""
+
+from .errors import (
+    ArtifactError,
+    ConfigurationError,
+    LicenseError,
+    LicenseServiceError,
+    LICENSE_SERVICE_ERROR_CODES,
+    is_license_service_error_code,
+    ManifestError,
+    SlyBrowserError,
+    WebDriverError,
+)
+from .browser import (
+    launch_playwright,
+    launch_playwright_async,
+    launch_playwright_persistent,
+    launch_playwright_persistent_async,
+)
+from .automation import AutomationBackend, AutomationCapability, automation_capability, validate_playwright_version
+from .launcher import LaunchPlan, prepare_launch
+from .webdriver import (
+    HumanizeConfig,
+    SlyWebDriverElement,
+    SlyWebDriverService,
+    SlyWebDriverSession,
+    WebDriverVersions,
+    launch,
+    launch_webdriver,
+)
+from .license import LicenseClaims, LicenseVerifier
+from .manifest import ReleaseManifest, verify_release_manifest
+from .installer import BrowserInstallation, install_granted_browser
+from .licensed import (
+    install_authorized,
+    install_latest,
+    launch_authorized,
+    launch_authorized_playwright,
+    launch_authorized_playwright_async,
+    launch_authorized_playwright_persistent,
+    launch_authorized_playwright_persistent_async,
+    launch_latest,
+    launch_latest_playwright,
+    launch_latest_playwright_async,
+    launch_latest_playwright_persistent,
+    launch_latest_playwright_persistent_async,
+    prepare_authorized_browser,
+    prepare_latest_authorized_browser,
+)
+from .service import (
+    LicenseAuthorization,
+    LicenseInfo,
+    LicenseServiceClient,
+    LicensedSessionGrant,
+    RuntimeActivationGrant,
+    RuntimeDownloadTicket,
+    RuntimeHeartbeatGrant,
+    RuntimeSessionGrant,
+    SealedLicenseImportResult,
+    import_license_file_to_sealed_authorization,
+    read_license_authorization,
+)
+
+__all__ = [
+    "ArtifactError",
+    "AutomationBackend",
+    "AutomationCapability",
+    "ConfigurationError",
+    "LaunchPlan",
+    "LicenseClaims",
+    "LicenseError",
+    "LicenseServiceError",
+    "LICENSE_SERVICE_ERROR_CODES",
+    "is_license_service_error_code",
+    "LicenseVerifier",
+    "ManifestError",
+    "ReleaseManifest",
+    "SlyBrowserError",
+    "WebDriverError",
+    "HumanizeConfig",
+    "SlyWebDriverElement",
+    "SlyWebDriverService",
+    "SlyWebDriverSession",
+    "WebDriverVersions",
+    "launch",
+    "launch_webdriver",
+    "launch_playwright",
+    "launch_playwright_async",
+    "launch_playwright_persistent",
+    "launch_playwright_persistent_async",
+    "automation_capability",
+    "validate_playwright_version",
+    "prepare_launch",
+    "verify_release_manifest",
+    "BrowserInstallation",
+    "LicenseAuthorization",
+    "LicenseInfo",
+    "LicenseServiceClient",
+    "LicensedSessionGrant",
+    "RuntimeActivationGrant",
+    "RuntimeDownloadTicket",
+    "RuntimeHeartbeatGrant",
+    "RuntimeSessionGrant",
+    "SealedLicenseImportResult",
+    "install_granted_browser",
+    "install_authorized",
+    "install_latest",
+    "launch_authorized",
+    "launch_authorized_playwright",
+    "launch_authorized_playwright_async",
+    "launch_authorized_playwright_persistent",
+    "launch_authorized_playwright_persistent_async",
+    "launch_latest",
+    "launch_latest_playwright",
+    "launch_latest_playwright_async",
+    "launch_latest_playwright_persistent",
+    "launch_latest_playwright_persistent_async",
+    "prepare_authorized_browser",
+    "prepare_latest_authorized_browser",
+    "import_license_file_to_sealed_authorization",
+    "read_license_authorization",
+]
+
+__version__ = "0.1.0"

slybrowser/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

slybrowser/automation.py

@@ -0,0 +1,86 @@
+"""Automation backend selection and framework binding compatibility."""
+
+from __future__ import annotations
+
+from importlib import metadata
+from typing import Literal, TypedDict
+
+from .errors import ConfigurationError
+
+AutomationBackend = Literal["project-webdriver", "playwright"]
+
+
+class AutomationCapability(TypedDict, total=False):
+    backend: AutomationBackend
+    language: Literal["python"]
+    framework_version: str
+    native_humanize: bool
+    persistent_context: bool
+
+
+_SUPPORTED_PLAYWRIGHT_LINES = frozenset({"1.62"})
+
+
+def validate_playwright_version(version: str) -> str:
+    parts = version.split("+", 1)[0].split("-", 1)[0].split(".")
+    if len(parts) < 2 or not all(part.isdigit() for part in parts):
+        raise ConfigurationError(
+            f"Invalid Playwright version: {version}",
+            code="framework_version_invalid",
+        )
+    line = ".".join(parts[:2])
+    if line not in _SUPPORTED_PLAYWRIGHT_LINES:
+        supported = ", ".join(sorted(_SUPPORTED_PLAYWRIGHT_LINES))
+        raise ConfigurationError(
+            f"Unsupported Playwright version {version}; supported lines: {supported}",
+            code="framework_version_unsupported",
+        )
+    return version
+
+
+def resolve_playwright_version(explicit: str | None = None) -> str:
+    if explicit is not None:
+        return validate_playwright_version(explicit)
+    try:
+        return validate_playwright_version(metadata.version("playwright"))
+    except metadata.PackageNotFoundError as error:
+        raise ConfigurationError(
+            "Unable to determine the installed Playwright package version; "
+            "pass framework_version explicitly",
+            code="framework_version_missing",
+        ) from error
+
+
+def require_playwright_humanize_support(requested: bool) -> None:
+    _ = requested
+
+
+def automation_capability(
+    backend: AutomationBackend = "project-webdriver",
+    *,
+    framework_version: str | None = None,
+) -> AutomationCapability:
+    if backend == "project-webdriver":
+        if framework_version is not None:
+            raise ConfigurationError(
+                "Project WebDriver does not accept framework_version",
+                code="framework_version_forbidden",
+            )
+        return {
+            "backend": backend,
+            "language": "python",
+            "native_humanize": True,
+            "persistent_context": True,
+        }
+    if backend != "playwright":
+        raise ConfigurationError(
+            f"Unsupported Python automation backend: {backend}",
+            code="automation_backend_unsupported",
+        )
+    return {
+        "backend": backend,
+        "language": "python",
+        "framework_version": resolve_playwright_version(framework_version),
+        "native_humanize": True,
+        "persistent_context": True,
+    }

slybrowser/browser.py

@@ -0,0 +1,306 @@
+"""Framework adapters that launch the native SlyBrowser executable."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from .automation import require_playwright_humanize_support, resolve_playwright_version
+from .errors import ConfigurationError
+from .launcher import LaunchPlan, prepare_launch, wait_for_native_ready
+from .webdriver import _release_root_from_lease, resolve_humanize_config
+
+
+def _launch_arguments(
+    launch_options: Mapping[str, Any] | None,
+    handoff_arguments: tuple[str, ...],
+) -> dict[str, Any]:
+    result = dict(launch_options or {})
+    if "executable_path" in result or "executablePath" in result:
+        raise ConfigurationError(
+            "The browser executable must be passed to the SlyBrowser adapter",
+            code="executable_option_conflict",
+        )
+    existing_arguments = result.get("args", [])
+    if not isinstance(existing_arguments, (list, tuple)) or any(
+        not isinstance(argument, str) for argument in existing_arguments
+    ):
+        raise ConfigurationError("Playwright args must be a string array", code="config_invalid")
+    result["args"] = [*handoff_arguments, *existing_arguments]
+    return result
+
+
+def _camel_humanize_config(config: object) -> dict[str, int]:
+    return {
+        "mouseStepsMin": config.mouse_steps_min,
+        "mouseStepsMax": config.mouse_steps_max,
+        "mouseStepDelayMin": config.mouse_step_delay_min,
+        "mouseStepDelayMax": config.mouse_step_delay_max,
+        "clickHoldMin": config.click_hold_min,
+        "clickHoldMax": config.click_hold_max,
+        "keyDelayMin": config.key_delay_min,
+        "keyDelayMax": config.key_delay_max,
+        "thinkDelayMin": config.think_delay_min,
+        "thinkDelayMax": config.think_delay_max,
+    }
+
+
+def _native_humanize_control(
+    *,
+    humanize: bool,
+    human_preset: str,
+    human_config: Mapping[str, int | float] | None,
+    human_seed: int | None,
+) -> dict[str, Any] | None:
+    if not humanize:
+        return None
+    if human_seed is not None and (not isinstance(human_seed, int) or human_seed < 0):
+        raise ConfigurationError("Native Humanize seed must be a non-negative integer", code="humanize_seed_invalid")
+    return {
+        "schemaVersion": 1,
+        "kind": "slybrowser.native-humanize-control",
+        "backend": "playwright",
+        "humanize": {
+            "enabled": True,
+            "version": 1,
+            "preset": human_preset,
+            "config": _camel_humanize_config(resolve_humanize_config(human_preset, human_config)),
+            **({} if human_seed is None else {"seed": human_seed}),
+        },
+    }
+
+
+def _validate_native_ready(native_ready: bool, native_ready_timeout: float) -> None:
+    if native_ready and (not isinstance(native_ready_timeout, (int, float)) or native_ready_timeout <= 0):
+        raise ConfigurationError("native_ready_timeout must be positive", code="config_invalid")
+
+
+def _close_runtime(runtime: Any) -> None:
+    close = getattr(runtime, "close", None)
+    if callable(close):
+        try:
+            close()
+        except Exception:
+            pass
+
+
+async def _close_runtime_async(runtime: Any) -> None:
+    import inspect
+
+    close = getattr(runtime, "close", None)
+    if callable(close):
+        try:
+            result = close()
+            if inspect.isawaitable(result):
+                await result
+        except Exception:
+            pass
+
+
+def _wait_if_requested(plan: LaunchPlan, native_ready: bool, native_ready_timeout: float) -> None:
+    if native_ready:
+        wait_for_native_ready(plan, timeout=native_ready_timeout)
+
+
+def launch_playwright(
+    playwright: Any,
+    executable: str | Path,
+    lease: str | bytes | Mapping[str, Any],
+    *,
+    profile: Mapping[str, Any] | None = None,
+    launch_options: Mapping[str, Any] | None = None,
+    temp_root: str | Path | None = None,
+    framework_version: str | None = None,
+    humanize: bool = False,
+    human_preset: str = "default",
+    human_config: Mapping[str, int | float] | None = None,
+    human_seed: int | None = None,
+    runtime_handoff: Mapping[str, Any] | None = None,
+    allow_runtime_activation_ticket: bool = False,
+    release_root: str | Path | None = None,
+    native_ready: bool = False,
+    native_ready_timeout: float = 15.0,
+) -> Any:
+    """Launch a non-persistent Playwright browser using an existing Playwright object."""
+
+    resolve_playwright_version(framework_version)
+    require_playwright_humanize_support(humanize)
+    _validate_native_ready(native_ready, native_ready_timeout)
+    with prepare_launch(
+        executable,
+        profile or {},
+        lease,
+        temp_root=temp_root,
+        runtime_handoff=runtime_handoff,
+        allow_runtime_activation_ticket=allow_runtime_activation_ticket,
+        release_root=Path(release_root).expanduser().resolve() if release_root is not None else _release_root_from_lease(executable, lease),
+        native_ready=native_ready,
+        humanize_control=_native_humanize_control(
+            humanize=humanize,
+            human_preset=human_preset,
+            human_config=human_config,
+            human_seed=human_seed,
+        ),
+    ) as plan:
+        options = _launch_arguments(launch_options, plan.arguments)
+        runtime = playwright.chromium.launch(executable_path=str(plan.executable), **options)
+        try:
+            _wait_if_requested(plan, native_ready, native_ready_timeout)
+            return runtime
+        except BaseException:
+            _close_runtime(runtime)
+            raise
+
+
+async def launch_playwright_async(
+    playwright: Any,
+    executable: str | Path,
+    lease: str | bytes | Mapping[str, Any],
+    *,
+    profile: Mapping[str, Any] | None = None,
+    launch_options: Mapping[str, Any] | None = None,
+    temp_root: str | Path | None = None,
+    framework_version: str | None = None,
+    humanize: bool = False,
+    human_preset: str = "default",
+    human_config: Mapping[str, int | float] | None = None,
+    human_seed: int | None = None,
+    runtime_handoff: Mapping[str, Any] | None = None,
+    allow_runtime_activation_ticket: bool = False,
+    release_root: str | Path | None = None,
+    native_ready: bool = False,
+    native_ready_timeout: float = 15.0,
+) -> Any:
+    resolve_playwright_version(framework_version)
+    require_playwright_humanize_support(humanize)
+    _validate_native_ready(native_ready, native_ready_timeout)
+    with prepare_launch(
+        executable,
+        profile or {},
+        lease,
+        temp_root=temp_root,
+        runtime_handoff=runtime_handoff,
+        allow_runtime_activation_ticket=allow_runtime_activation_ticket,
+        release_root=Path(release_root).expanduser().resolve() if release_root is not None else _release_root_from_lease(executable, lease),
+        native_ready=native_ready,
+        humanize_control=_native_humanize_control(
+            humanize=humanize,
+            human_preset=human_preset,
+            human_config=human_config,
+            human_seed=human_seed,
+        ),
+    ) as plan:
+        options = _launch_arguments(launch_options, plan.arguments)
+        runtime = await playwright.chromium.launch(executable_path=str(plan.executable), **options)
+        try:
+            _wait_if_requested(plan, native_ready, native_ready_timeout)
+            return runtime
+        except BaseException:
+            await _close_runtime_async(runtime)
+            raise
+
+
+def launch_playwright_persistent(
+    playwright: Any,
+    user_data_dir: str | Path,
+    executable: str | Path,
+    lease: str | bytes | Mapping[str, Any],
+    *,
+    profile: Mapping[str, Any] | None = None,
+    launch_options: Mapping[str, Any] | None = None,
+    temp_root: str | Path | None = None,
+    framework_version: str | None = None,
+    humanize: bool = False,
+    human_preset: str = "default",
+    human_config: Mapping[str, int | float] | None = None,
+    human_seed: int | None = None,
+    runtime_handoff: Mapping[str, Any] | None = None,
+    allow_runtime_activation_ticket: bool = False,
+    release_root: str | Path | None = None,
+    native_ready: bool = False,
+    native_ready_timeout: float = 15.0,
+) -> Any:
+    resolve_playwright_version(framework_version)
+    require_playwright_humanize_support(humanize)
+    _validate_native_ready(native_ready, native_ready_timeout)
+    with prepare_launch(
+        executable,
+        profile or {},
+        lease,
+        temp_root=temp_root,
+        runtime_handoff=runtime_handoff,
+        allow_runtime_activation_ticket=allow_runtime_activation_ticket,
+        release_root=Path(release_root).expanduser().resolve() if release_root is not None else _release_root_from_lease(executable, lease),
+        native_ready=native_ready,
+        humanize_control=_native_humanize_control(
+            humanize=humanize,
+            human_preset=human_preset,
+            human_config=human_config,
+            human_seed=human_seed,
+        ),
+    ) as plan:
+        options = _launch_arguments(launch_options, plan.arguments)
+        runtime = playwright.chromium.launch_persistent_context(
+            str(Path(user_data_dir).expanduser().resolve()),
+            executable_path=str(plan.executable),
+            **options,
+        )
+        try:
+            _wait_if_requested(plan, native_ready, native_ready_timeout)
+            return runtime
+        except BaseException:
+            _close_runtime(runtime)
+            raise
+
+
+async def launch_playwright_persistent_async(
+    playwright: Any,
+    user_data_dir: str | Path,
+    executable: str | Path,
+    lease: str | bytes | Mapping[str, Any],
+    *,
+    profile: Mapping[str, Any] | None = None,
+    launch_options: Mapping[str, Any] | None = None,
+    temp_root: str | Path | None = None,
+    framework_version: str | None = None,
+    humanize: bool = False,
+    human_preset: str = "default",
+    human_config: Mapping[str, int | float] | None = None,
+    human_seed: int | None = None,
+    runtime_handoff: Mapping[str, Any] | None = None,
+    allow_runtime_activation_ticket: bool = False,
+    release_root: str | Path | None = None,
+    native_ready: bool = False,
+    native_ready_timeout: float = 15.0,
+) -> Any:
+    resolve_playwright_version(framework_version)
+    require_playwright_humanize_support(humanize)
+    _validate_native_ready(native_ready, native_ready_timeout)
+    with prepare_launch(
+        executable,
+        profile or {},
+        lease,
+        temp_root=temp_root,
+        runtime_handoff=runtime_handoff,
+        allow_runtime_activation_ticket=allow_runtime_activation_ticket,
+        release_root=Path(release_root).expanduser().resolve() if release_root is not None else _release_root_from_lease(executable, lease),
+        native_ready=native_ready,
+        humanize_control=_native_humanize_control(
+            humanize=humanize,
+            human_preset=human_preset,
+            human_config=human_config,
+            human_seed=human_seed,
+        ),
+    ) as plan:
+        options = _launch_arguments(launch_options, plan.arguments)
+        runtime = await playwright.chromium.launch_persistent_context(
+            str(Path(user_data_dir).expanduser().resolve()),
+            executable_path=str(plan.executable),
+            **options,
+        )
+        try:
+            _wait_if_requested(plan, native_ready, native_ready_timeout)
+            return runtime
+        except BaseException:
+            await _close_runtime_async(runtime)
+            raise

slybrowser/canonical.py

@@ -0,0 +1,41 @@
+"""Canonical JSON and bounded base64url helpers shared by signed documents."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import Any
+
+_BASE64URL_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def canonical_json(value: Any) -> bytes:
+    """Serialize JSON deterministically for signature generation and verification."""
+
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+def decode_base64url(value: str, *, max_bytes: int) -> bytes:
+    if not isinstance(value, str) or not value or not _BASE64URL_RE.fullmatch(value):
+        raise ValueError("value is not unpadded base64url")
+    if len(value) > ((max_bytes + 2) // 3) * 4:
+        raise ValueError("decoded value exceeds size limit")
+    padding = "=" * (-len(value) % 4)
+    try:
+        decoded = base64.urlsafe_b64decode(value + padding)
+    except (ValueError, TypeError) as exc:
+        raise ValueError("invalid base64url value") from exc
+    if len(decoded) > max_bytes:
+        raise ValueError("decoded value exceeds size limit")
+    return decoded
+
+
+def encode_base64url(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")