clearcote 0.1.0__py3-none-any.whl

clearcote/__init__.py

@@ -0,0 +1,120 @@
+"""Clearcote — Playwright drop-in (Python).
+
+    from clearcote import launch
+
+    browser = launch(fingerprint="seed-123", platform="windows")
+    page = browser.new_page()
+    page.goto("https://abrahamjuliot.github.io/creepjs/")
+    browser.close()
+
+launch() returns a standard Playwright sync ``Browser`` backed by the verified Clearcote
+binary (auto-downloaded + SHA-256 checked on first use, then cached). Every Playwright launch
+option (headless, proxy, args, timeout, ...) passes through; the fingerprint kwargs map to the
+engine switches.
+"""
+
+import atexit
+import os
+import sys
+
+from ._fingerprint import FINGERPRINT_KEYS, fingerprint_args
+from .download import ensure_binary
+from .release import RELEASE
+
+__all__ = [
+    "launch",
+    "launch_persistent_context",
+    "executable_path",
+    "download",
+    "RELEASE",
+    "__version__",
+]
+__version__ = "0.1.0"
+
+_pw = None  # the shared, lazily-started Playwright driver (one per process)
+
+
+def _stop_quietly(pw):
+    try:
+        pw.stop()
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _playwright():
+    global _pw
+    if _pw is None:
+        try:
+            from playwright.sync_api import sync_playwright
+        except ImportError as exc:
+            raise RuntimeError(
+                "clearcote requires Playwright. Install it with:\n    pip install playwright\n"
+                "(You do NOT need 'playwright install' — Clearcote uses its own browser binary.)"
+            ) from exc
+        _pw = sync_playwright().start()
+        atexit.register(_stop_quietly, _pw)
+    return _pw
+
+
+def _resolve_binary(executable_path=None, cache_dir=None, quiet=False):
+    if executable_path:
+        return executable_path
+    env = os.environ.get("CLEARCOTE_BINARY")
+    if env:
+        return env
+    return ensure_binary(cache_dir=cache_dir, quiet=quiet)
+
+
+def executable_path(executable_path=None, cache_dir=None, quiet=False):
+    """Resolve the Clearcote chrome.exe path, downloading + verifying it if needed.
+
+    Order: explicit ``executable_path`` > ``CLEARCOTE_BINARY`` env > auto-download.
+    """
+    return _resolve_binary(executable_path, cache_dir, quiet)
+
+
+def download(cache_dir=None, quiet=False):
+    """Pre-fetch + verify the Clearcote binary without launching. Returns the chrome.exe path."""
+    return ensure_binary(cache_dir=cache_dir, quiet=quiet)
+
+
+def _guard(exe):
+    if sys.platform != "win32":
+        raise RuntimeError(
+            f"Clearcote {RELEASE['version']} ships a Windows x64 binary only — it cannot launch "
+            f"on {sys.platform!r}.\nRun on Windows, or pass executable_path=... to a compatible "
+            f"binary.\n(The binary downloaded and verified fine; it is cached at: {exe})"
+        )
+
+
+def _prepare(kwargs):
+    fp = {k: kwargs.pop(k) for k in list(kwargs) if k in FINGERPRINT_KEYS}
+    exe_path = kwargs.pop("executable_path", None)
+    extra_args = kwargs.pop("args", None)
+    cache_dir = kwargs.pop("cache_dir", None)
+    quiet = kwargs.pop("quiet", False)
+    exe = _resolve_binary(exe_path, cache_dir, quiet)
+    _guard(exe)
+    args = fingerprint_args(fp) + list(extra_args or [])
+    return exe, args, kwargs
+
+
+def launch(**kwargs):
+    """Launch Clearcote and return a standard Playwright sync ``Browser``.
+
+    Fingerprint kwargs: fingerprint, platform, platform_version, brand, brand_version,
+    gpu_vendor, gpu_renderer, hardware_concurrency, location, timezone, webrtc_ip,
+    disable_gpu_fingerprint. All other kwargs (headless, proxy, args, timeout, ...) pass
+    through to Playwright's chromium.launch().
+    """
+    exe, args, pw_kwargs = _prepare(kwargs)
+    return _playwright().chromium.launch(executable_path=exe, args=args, **pw_kwargs)
+
+
+def launch_persistent_context(user_data_dir, **kwargs):
+    """Launch Clearcote with a persistent profile directory; returns a Playwright
+    ``BrowserContext`` (cookies/storage persist in ``user_data_dir``)."""
+    exe, args, pw_kwargs = _prepare(kwargs)
+    return _playwright().chromium.launch_persistent_context(
+        user_data_dir, executable_path=exe, args=args, **pw_kwargs
+    )

clearcote/_fingerprint.py

@@ -0,0 +1,50 @@
+"""Map Clearcote fingerprint kwargs to Chromium command-line switches.
+
+Switch names mirror components/ungoogled/ungoogled_switches.cc
+(see patches/000-fingerprint-switches.patch).
+"""
+
+# kwargs accepted by launch()/launch_persistent_context() that are fingerprint options
+# (everything else is passed straight through to Playwright).
+FINGERPRINT_KEYS = (
+    "fingerprint",
+    "platform",
+    "platform_version",
+    "brand",
+    "brand_version",
+    "gpu_vendor",
+    "gpu_renderer",
+    "hardware_concurrency",
+    "location",
+    "timezone",
+    "webrtc_ip",
+    "disable_gpu_fingerprint",
+)
+
+# kwarg -> switch name (without leading "--"). disable_gpu_fingerprint is a boolean flag,
+# handled separately below.
+_FLAGS = {
+    "fingerprint": "fingerprint",
+    "platform": "fingerprint-platform",
+    "platform_version": "fingerprint-platform-version",
+    "brand": "fingerprint-brand",
+    "brand_version": "fingerprint-brand-version",
+    "gpu_vendor": "fingerprint-gpu-vendor",
+    "gpu_renderer": "fingerprint-gpu-renderer",
+    "hardware_concurrency": "fingerprint-hardware-concurrency",
+    "location": "fingerprint-location",
+    "timezone": "timezone",
+    "webrtc_ip": "webrtc-ip",
+}
+
+
+def fingerprint_args(opts):
+    """Build the Chromium switches for a dict of fingerprint options."""
+    args = []
+    for key, flag in _FLAGS.items():
+        value = opts.get(key)
+        if value is not None and value != "":
+            args.append(f"--{flag}={value}")
+    if opts.get("disable_gpu_fingerprint"):
+        args.append("--disable-gpu-fingerprint")
+    return args

clearcote/download.py

@@ -0,0 +1,138 @@
+"""Resolve the Clearcote browser binary: download the pinned release, verify its SHA-256
+against the value baked into the SDK, extract it to a per-version cache, and return the path
+to chrome.exe. The hash check is mandatory — a mismatch raises and the partial file is removed.
+
+Uses only the standard library (urllib + hashlib + zipfile) — no extra dependencies.
+"""
+
+import hashlib
+import os
+import shutil
+import sys
+import urllib.request
+import zipfile
+
+from .release import RELEASE
+
+
+def _log(quiet, msg):
+    if not quiet:
+        sys.stderr.write(f"[clearcote] {msg}\n")
+        sys.stderr.flush()
+
+
+def _cache_root():
+    env = os.environ.get("CLEARCOTE_CACHE")
+    if env:
+        return env
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser(r"~\AppData\Local")
+        return os.path.join(base, "clearcote", "Cache")
+    if sys.platform == "darwin":
+        return os.path.join(os.path.expanduser("~/Library/Caches"), "clearcote")
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache")
+    return os.path.join(base, "clearcote")
+
+
+def _find(dirpath, name):
+    name = name.lower()
+    for root, _dirs, files in os.walk(dirpath):
+        for f in files:
+            if f.lower() == name:
+                return os.path.join(root, f)
+    return None
+
+
+def _sha256_file(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _download(url, dest, quiet):
+    """Stream the download to dest, hashing as we go; return the hex digest."""
+    h = hashlib.sha256()
+    req = urllib.request.Request(url, headers={"User-Agent": "clearcote-sdk"})
+    with urllib.request.urlopen(req) as resp, open(dest, "wb") as out:  # noqa: S310
+        total = int(resp.headers.get("Content-Length") or RELEASE["size"])
+        seen = 0
+        last = -1
+        while True:
+            chunk = resp.read(1 << 20)
+            if not chunk:
+                break
+            out.write(chunk)
+            h.update(chunk)
+            seen += len(chunk)
+            if not quiet:
+                pct = int(seen * 100 / total) if total else 0
+                if pct != last and pct % 5 == 0:
+                    last = pct
+                    sys.stderr.write(
+                        f"\r[clearcote] downloading {pct}% "
+                        f"({seen // 10**6}/{total // 10**6} MB)"
+                    )
+                    sys.stderr.flush()
+    if not quiet:
+        sys.stderr.write("\n")
+        sys.stderr.flush()
+    return h.hexdigest()
+
+
+def ensure_binary(cache_dir=None, quiet=False):
+    """Ensure the Clearcote binary is present and verified; return the chrome.exe path.
+    Cached per release tag, so later calls are instant."""
+    base = os.path.join(cache_dir or _cache_root(), RELEASE["tag"])
+    browser_dir = os.path.join(base, "browser")
+    marker = os.path.join(base, ".verified")
+
+    if os.path.exists(marker):
+        cached = _find(browser_dir, "chrome.exe")
+        if cached:
+            return cached
+
+    os.makedirs(base, exist_ok=True)
+    zip_path = os.path.join(base, RELEASE["asset"])
+
+    _log(quiet, f"fetching Clearcote {RELEASE['version']} ({RELEASE['tag']}, "
+                f"~{RELEASE['size'] // 10**6} MB)")
+    got = _download(RELEASE["url"], zip_path, quiet)
+
+    _log(quiet, "verifying SHA-256")
+    if got.lower() != RELEASE["sha256"].lower():
+        try:
+            os.remove(zip_path)
+        except OSError:
+            pass
+        raise RuntimeError(
+            "Clearcote archive SHA-256 mismatch — refusing to use it.\n"
+            f"  expected {RELEASE['sha256']}\n  got      {got}"
+        )
+
+    _log(quiet, "extracting")
+    if os.path.isdir(browser_dir):
+        shutil.rmtree(browser_dir, ignore_errors=True)
+    with zipfile.ZipFile(zip_path) as z:
+        z.extractall(browser_dir)
+
+    exe = _find(browser_dir, "chrome.exe")
+    if not exe:
+        raise RuntimeError("Clearcote archive verified but chrome.exe was not found inside it.")
+
+    exe_hash = _sha256_file(exe)
+    if exe_hash.lower() != RELEASE["exe_sha256"].lower():
+        raise RuntimeError(
+            "Clearcote chrome.exe SHA-256 mismatch — refusing to use it.\n"
+            f"  expected {RELEASE['exe_sha256']}\n  got      {exe_hash}"
+        )
+
+    with open(marker, "w", encoding="utf-8") as f:
+        f.write(RELEASE["sha256"] + "\n")
+    try:
+        os.remove(zip_path)  # reclaim ~250 MB; keep only the extracted tree
+    except OSError:
+        pass
+    _log(quiet, f"ready: {exe}")
+    return exe

clearcote/release.py

@@ -0,0 +1,23 @@
+"""Pinned Clearcote release the SDK downloads and verifies.
+
+Bumping to a new browser build = updating these values (and the version in pyproject.toml).
+The sha256 is the single trust anchor for the auto-download: if you trust this package, the
+hash check guarantees you run exactly the published, signed binary. Published checksums + GPG
+signatures live on the release page.
+"""
+
+RELEASE = {
+    "tag": "v0.1.0-pre.2",
+    "version": "149.0.7827.114",
+    "asset": "clearcote-149.0.7827.114-windows-x64.zip",
+    "url": (
+        "https://github.com/clearcotelabs/clearcote-browser/releases/download/"
+        "v0.1.0-pre.2/clearcote-149.0.7827.114-windows-x64.zip"
+    ),
+    # SHA-256 of the zip — verified after download; a mismatch is a hard failure.
+    "sha256": "4071aa06add252caa274c4f52dfe2e8eaede4eb37cf55be6fb6f8e3c28bcf256",
+    # SHA-256 of chrome.exe inside the zip — verified after extraction (defense in depth).
+    "exe_sha256": "5743595256c89c6874804bf3315acce592fc7f1883760c8d380c010151a73b23",
+    "size": 253015969,
+    "os": "win32",
+}

clearcote-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: clearcote
+Version: 0.1.0
+Summary: Playwright drop-in for the Clearcote anti-fingerprint Chromium build. launch() returns a standard Playwright Browser backed by the verified Clearcote binary, which is auto-downloaded and SHA-256 checked.
+Project-URL: Homepage, https://github.com/clearcotelabs/clearcote-browser
+Project-URL: Repository, https://github.com/clearcotelabs/clearcote-browser
+Project-URL: Issues, https://github.com/clearcotelabs/clearcote-browser/issues
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: anti-detect,anti-fingerprint,automation,chromium,clearcote,farbling,fingerprint,playwright,stealth,ungoogled
+Requires-Python: >=3.8
+Requires-Dist: playwright>=1.40
+Description-Content-Type: text/markdown
+
+# clearcote (Python SDK)
+
+A **Playwright drop-in** for [Clearcote](https://github.com/clearcotelabs/clearcote-browser) — the
+open, reproducible, anti-fingerprint Chromium build. `launch()` returns a standard Playwright
+`Browser`, so migrating is a one-line import change.
+
+The verified Clearcote binary is **auto-downloaded and SHA-256 checked** on first use, then cached —
+no zips or paths to manage.
+
+> **Platform:** Clearcote currently ships a **Windows x64** binary, so `launch()` runs on Windows.
+> (The SDK will download + verify the binary on any OS — handy for packaging — but only launches it
+> on Windows. Linux/macOS builds are on the [roadmap](../../ROADMAP.md).)
+
+## Install
+
+```bash
+pip install clearcote
+```
+
+`playwright` is pulled in as a dependency. You do **not** need to run `playwright install`
+(Clearcote uses its own browser binary, not Playwright's bundled Chromium).
+
+## Usage
+
+```python
+from clearcote import launch
+
+browser = launch(
+    fingerprint="user-7423",        # per-eTLD+1 seed: same seed => same identity, different => unlinkable
+    platform="windows",
+    timezone="America/New_York",
+    headless=False,
+)
+page = browser.new_page()
+page.goto("https://abrahamjuliot.github.io/creepjs/")
+# ... standard Playwright (sync API) from here ...
+browser.close()
+```
+
+Already using Playwright? Swap `p.chromium.launch(...)` for `launch(...)` from `clearcote` — the
+returned object is a normal Playwright `Browser`. (One shared Playwright driver is started lazily
+and stopped at interpreter exit.)
+
+### Through a proxy (report the proxy's IP, not your host's)
+
+```python
+browser = launch(
+    fingerprint="user-7423",
+    proxy={"server": "http://host:8080", "username": "u", "password": "p"},  # standard Playwright option
+    timezone="America/New_York",
+    webrtc_ip="203.0.113.10",       # make WebRTC report the proxy egress IP
+)
+```
+
+### Persistent profile
+
+```python
+from clearcote import launch_persistent_context
+
+context = launch_persistent_context(
+    "./profile-7423",
+    fingerprint="user-7423",
+    platform="windows",
+)
+```
+
+## Fingerprint options
+
+All optional. Anything not listed here is passed straight through to Playwright
+(`headless`, `proxy`, `args`, `timeout`, `slow_mo`, …).
+
+| Kwarg | Switch | Meaning |
+|---|---|---|
+| `fingerprint` | `--fingerprint` | Master seed (per-eTLD+1 farbling root). `str` or `int`. |
+| `platform` | `--fingerprint-platform` | `"windows"` \| `"linux"` \| `"macos"`. |
+| `platform_version` | `--fingerprint-platform-version` | UA-CH platform version. |
+| `brand` | `--fingerprint-brand` | `"Chrome"` \| `"Edge"` \| `"Opera"` \| `"Vivaldi"`. |
+| `brand_version` | `--fingerprint-brand-version` | Brand version. |
+| `gpu_vendor` | `--fingerprint-gpu-vendor` | WebGL UNMASKED vendor. |
+| `gpu_renderer` | `--fingerprint-gpu-renderer` | WebGL UNMASKED renderer. |
+| `hardware_concurrency` | `--fingerprint-hardware-concurrency` | `navigator.hardwareConcurrency`. |
+| `location` | `--fingerprint-location` | `"lat,lng"` (only when geo permission is granted). |
+| `timezone` | `--timezone` | IANA timezone, e.g. `"America/New_York"`. |
+| `webrtc_ip` | `--webrtc-ip` | WebRTC egress IP to report (your proxy IP). |
+| `disable_gpu_fingerprint` | `--disable-gpu-fingerprint` | Turn off GPU/WebGL spoofing. |
+
+## API
+
+- `launch(**options)` → Playwright `Browser`.
+- `launch_persistent_context(user_data_dir, **options)` → Playwright `BrowserContext`.
+- `executable_path(executable_path=None, cache_dir=None, quiet=False)` → `str` — resolve (download/verify if needed) the chrome.exe path.
+- `download(cache_dir=None, quiet=False)` → `str` — pre-fetch + verify without launching.
+- `RELEASE` — the pinned release metadata (tag, version, sha256).
+
+## Binary resolution & verification
+
+`launch()` resolves the browser in this order:
+
+1. `executable_path=` argument, if given;
+2. `CLEARCOTE_BINARY` environment variable, if set;
+3. otherwise **download** the pinned release, **verify its SHA-256** (the hash is baked into this
+   package — it's the trust anchor), extract to a per-version cache, and verify the extracted
+   `chrome.exe` hash too.
+
+Cache location (override with `CLEARCOTE_CACHE`):
+- Windows: `%LOCALAPPDATA%\clearcote\Cache\<tag>`
+- macOS: `~/Library/Caches/clearcote/<tag>`
+- Linux: `${XDG_CACHE_HOME:-~/.cache}/clearcote/<tag>`
+
+A SHA-256 mismatch is a hard error — the SDK refuses to run an unverified binary. You can
+independently confirm the published checksums and GPG signatures on the
+[release page](https://github.com/clearcotelabs/clearcote-browser/releases).
+
+## License
+
+BSD-3-Clause. See [LICENSE](../../LICENSE).

clearcote-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+clearcote/__init__.py,sha256=NHQnCFxQ6BVjwJ7PvSQ4YwjEabNXD0XpXpUds5x165c,4094
+clearcote/_fingerprint.py,sha256=6WUeXKzR8vtFotZlvZ3PvgmsrhQmqDOrpQ_JHSU4tSI,1581
+clearcote/download.py,sha256=OB_4AVAU1Vo1qxPB-B71CfQz0_pW2soUnZA7ZuAWaVQ,4635
+clearcote/release.py,sha256=oQ2krf2Udz48MZ77geCYM8HGR5rIvNpK1uSQ_Lgmp-E,1063
+clearcote-0.1.0.dist-info/METADATA,sha256=2f8gngGNuQp1Fx5mhEWg9OCR_wJDbk-wSErXXG-gbzU,5398
+clearcote-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+clearcote-0.1.0.dist-info/licenses/LICENSE,sha256=onkDgSIh3yfBM40kQLPu2Mg_Ph1Ym8D9yYMaIkYjbEk,1731
+clearcote-0.1.0.dist-info/RECORD,,

clearcote-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

clearcote-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,34 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Clearcote Labs and the Clearcote contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+This license applies to Clearcote's own source code and patches. Upstream
+components (Chromium, ungoogled-chromium, and others) are distributed under
+their respective licenses; see CREDITS.md.