chore: prepare 0.4.0 — version bump, Pro tier changelog + README + license v1.1

Replace the same-origin checksum with a detached Ed25519 signature
(SHA256SUMS.sig) verified against a pinned public key before extraction,
closing #308: a compromised download mirror can no longer certify a
tampered binary. The signed manifest also binds the release version,
rejecting a forced downgrade to an older signed build.

Verification is mandatory and non-bypassable on the official download path;
custom CLOAKBROWSER_DOWNLOAD_URL mirrors keep the legacy skippable checksum.
Silent auto-update is preserved for everyone because only a constant public
key is pinned, not per-version hashes. Older installed wrappers are
unaffected — the version= line is ignored by their checksum parser.

Python uses cryptography; JS uses node:crypto. Adds tamper, downgrade, and
fail-closed tests in both languages.

.dockerignore

@@ -0,0 +1,5 @@
+# Never let signing material enter a Docker build context / image.
+# The test image (test-infra/Dockerfile.test) uses selective COPY today, but
+# this is defense-in-depth against a future `COPY . .`.
+test-infra/signing/
+*.pem

.gitignore

@@ -73,3 +73,4 @@ captures
 .dolt/
 *.db
 .beads-credential-key
+.antigravitycli

BINARY-LICENSE.md

@@ -1,6 +1,6 @@
 # CloakBrowser Binary License
 
-**Version 1.0 — February 2026**
+**Version 1.1 — June 2026**
 
 Copyright (c) 2026 CloakHQ. All rights reserved.
 
@@ -14,7 +14,13 @@ The Binary is built on Chromium, which is open-source software by The Chromium A
 
 ## Grant of Use
 
-You are granted a non-exclusive, non-transferable, royalty-free license to use the Binary for personal or commercial purposes. No fees are required.
+You are granted a non-exclusive, non-transferable, royalty-free license to use the Binary for personal or commercial purposes, subject to the Version-Specific Terms below.
+
+## Version-Specific Terms
+
+Starting with Chromium 148, downloading the **latest major** Binary version requires an active CloakBrowser Pro subscription. Previous **major** versions (v146 and earlier) remain available at no cost under this license. Each time a new **major** Chromium version is released, the **prior major version** becomes available for free download. Minor and patch updates to the latest major version are part of the Pro subscription.
+
+Pro subscription details and pricing: https://cloakbrowser.dev
 
 ## Restrictions
 

CHANGELOG.md

@@ -6,7 +6,17 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi
 
 ---
 
-## [Unreleased]
+## [0.4.0] — 2026-06-22
+
+- **[wrapper]** **CloakBrowser Pro**: all launch functions now accept a `license_key` parameter (`licenseKey` in JS); a key can also be supplied via the `CLOAKBROWSER_LICENSE_KEY` environment variable or a `~/.cloakbrowser/license.key` file. With a valid key the latest binary is downloaded from cloakbrowser.dev; without one, the free binary continues to download from GitHub Releases exactly as before. License validation is cached locally for 24h, and the Pro binary is authenticated with the same pinned Ed25519 signature as the free binary. A valid key whose Pro download or signature check fails surfaces a clear error rather than silently downgrading to the free binary. Adds `validate_license`/`LicenseInfo` exports and a `tier` field on `binary_info()`. Details: https://cloakbrowser.dev
+- **[wrapper]** **Security**: downloaded binaries are now verified against a pinned Ed25519 signature on the published `SHA256SUMS` (a detached `SHA256SUMS.sig`), so a compromised download mirror can no longer certify a tampered binary — the previous same-origin checksum proved integrity but not authenticity (#308). The signed manifest also binds the release version, rejecting a forced downgrade to an older signed build. Verification is mandatory on the official download path; silent auto-update is preserved for everyone because only a constant public key is pinned, not per-version hashes. Older installed wrappers are unaffected.
+- **[wrapper]** Headed launches no longer apply a fixed emulated viewport on top of the real browser window — the page now tracks the actual window so window-geometry stays self-consistent. Headless keeps a deterministic viewport (unchanged). Applies across `launch`, `launch_context`, `launch_persistent_context` (+ async) and the JS Playwright/Puppeteer wrappers. Passing an explicit `viewport=`/`no_viewport` (Python) or `viewport`/`defaultViewport` (JS) still works exactly as before.
+- **[wrapper]** **Breaking**: removed the optional `patchright` backend. The `backend` parameter and `CLOAKBROWSER_BACKEND` environment variable no longer exist, and the `cloakbrowser[patchright]` extra is gone. Stock Playwright is now the only backend. The stealth binary handles automation-signal suppression at the C++ level — patchright added no measurable benefit on top of it (identical reCAPTCHA v3 score to plain Playwright) while breaking proxy auth and `add_init_script` (#27). Callers passing `backend=...` will get a `TypeError`; remove the argument.
+- **[binary]** **CloakBrowser Pro — first Pro build**: Chromium `148.0.7778.215.2` for linux-x64, linux-arm64, and windows-x64 — 59 source-level fingerprint patches (up from 58 on 146). macOS builds to follow. Available to Pro subscribers at cloakbrowser.dev; v146 remains free on GitHub Releases.
+- **[binary]** Rebased the full patch set across two Chromium major versions — 146 → 147 → 148 — re-applying and adapting every patch to current Chromium internals
+- **[binary]** Cross-API fingerprint consistency improvements for Chromium 148 profiles
+- **[binary]** WebRTC fingerprint hardening — network signals matched to real Chrome
+- **[binary]** Font metric alignment for Windows profiles via the opt-in `--fingerprint-windows-font-metrics` flag — requires Windows fonts installed (see README "Font Setup on Linux")
 
 ## [0.3.32] — 2026-06-20
 

README.md

@@ -49,11 +49,13 @@ Same API, same code — just swap the import. <strong>3 lines of code, 30 second
 - **Free and open source** — no subscriptions, no usage limits
 
 **Try it now** — no install needed:
+
 ```bash
 docker run --rm cloakhq/cloakbrowser cloaktest
 ```
 
 **Python:**
+
 ```python
 from cloakbrowser import launch
 
@@ -64,6 +66,7 @@ browser.close()
 ```
 
 **JavaScript (Playwright):**
+
 ```javascript
 import { launch } from 'cloakbrowser';
 
@@ -100,11 +103,13 @@ See [Troubleshooting](#troubleshooting) for site-specific issues (FingerprintJS,
 ## Install
 
 **Python:**
+
 ```bash
 pip install cloakbrowser
 ```
 
 **JavaScript / Node.js:**
+
 ```bash
 # With Playwright
 npm install cloakbrowser playwright-core
@@ -116,6 +121,7 @@ npm install cloakbrowser puppeteer-core
 On first run, the stealth Chromium binary is automatically downloaded (~200MB, cached locally).
 
 **Optional:** Auto-detect timezone/locale from proxy IP:
+
 ```bash
 pip install cloakbrowser[geoip]
 ```
@@ -136,22 +142,11 @@ page.goto("https://example.com")
 
 > ⭐ **Star** to show support — **[Watch releases](https://github.com/CloakHQ/CloakBrowser/subscription)** to get notified when new builds drop.
 
-## Browser Profile Manager
-
-Self-hosted alternative to Multilogin, GoLogin, and AdsPower. Create browser profiles with unique fingerprints, proxies, and persistent sessions. Launch and interact with them in your browser via noVNC.
-
-```bash
-docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager
-```
-
-Open [http://localhost:8080](http://localhost:8080). Create a profile. Click **Launch**. Done.
-
-→ **[CloakBrowser Manager](https://github.com/CloakHQ/CloakBrowser-Manager)** — free, open source (MIT)
-
 ---
 
-## Latest: v0.3.32 (Chromium 146.0.7680.177.5)
+## Latest: v0.4.0 — CloakBrowser Pro (Chromium 148.0.7778.215.2)
 
+- **CloakBrowser Pro** — the latest binary (Chromium 148.0.7778.215.2, 59 source-level patches) is now available to Pro subscribers; v146 stays free forever. Set a `license_key` (`licenseKey` in JS) or the `CLOAKBROWSER_LICENSE_KEY` env var and the wrapper fetches the latest build automatically. See [CloakBrowser Pro](#cloakbrowser-pro)
 - **58 fingerprint patches** — rendering consistency improvements across Linux and Windows, corrected GPU/display/graphics parameters to match stock Chrome 146 profiles
 - **Windows native GPU passthrough** — real hardware values pass through directly instead of being spoofed, matching real browser behavior
 - **HTTP proxy inline credentials** — new network-layer support for proxies with inline authentication
@@ -180,6 +175,28 @@ See the full [CHANGELOG.md](CHANGELOG.md) for details.
 
 CloakBrowser doesn't solve CAPTCHAs — it prevents them from appearing. No CAPTCHA-solving services, no proxy rotation built in — bring your own proxies, use the Playwright API you already know.
 
+## CloakBrowser Pro
+
+The wrapper (Python + JS) is MIT, free forever. The binary uses a delayed
+free-release model:
+
+- **Free (v146)** — the previous binary, on [GitHub Releases](https://github.com/CloakHQ/cloakbrowser/releases). Goes stale within weeks as detection evolves.
+- **Pro (latest, Chromium 148.0.7778.215.2)** — the newest patches and Chromium upgrades first, so the [results below](#test-results) stay green as anti-bot systems change. Linux + Windows (macOS coming).
+
+Anti-bot detection updates constantly, and an older binary degrades fast.
+Pro keeps you on the build that's actively maintained against it.
+
+Use Pro if CloakBrowser is part of production scraping, QA, monitoring, or
+automation where stale browser fingerprints cost you time or blocked runs.
+
+Activate with your license key (env var, `license_key=` param, or `~/.cloakbrowser/license.key`):
+
+```bash
+export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx
+```
+
+Pro plans → **[cloakbrowser.dev](https://cloakbrowser.dev)**
+
 ## Test Results
 
 All tests verified against live detection services. Last tested: Apr 2026 (Chromium 146).
@@ -254,7 +271,7 @@ The binary includes 58 source-level patches covering canvas, WebGL, audio, fonts
 
 These are compiled into the Chromium binary — not injected via JavaScript, not set via flags.
 
-Binary downloads are verified with SHA-256 checksums to ensure integrity.
+Binary downloads are verified against a pinned Ed25519 signature on the published checksums before extraction, so the download is confirmed authentic (genuinely ours) and not just intact. A compromised mirror cannot serve a tampered or downgraded binary.
 
 ## API
 
@@ -269,6 +286,9 @@ browser = launch()
 # Headed mode (see the browser window)
 browser = launch(headless=False)
 
+# Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
+browser = launch(license_key="cb_xxxxxxxx")
+
 # With proxy (HTTP or SOCKS5)
 browser = launch(proxy="http://user:pass@proxy:8080")
 browser = launch(proxy="socks5://user:pass@proxy:1080")
@@ -379,6 +399,7 @@ asyncio.run(main())
 Same as `launch_context()`, but with a persistent user profile. Cookies, localStorage, and cache persist across sessions.
 
 Use this when you need to:
+
 - **Stay logged in** across runs (cookies/sessions survive restarts)
 - **Bypass incognito detection** (some sites flag empty, ephemeral profiles)
 - **Load Chrome extensions** (extensions only work from a real user data dir)
@@ -479,6 +500,9 @@ import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';
 // Basic
 const browser = await launch();
 
+// Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
+const browser = await launch({ licenseKey: 'cb_xxxxxxxx' });
+
 // With options
 const browser = await launch({
   headless: false,
@@ -621,7 +645,7 @@ Access the original un-patched Playwright page at `page._original` if you need r
 | `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | Binary cache directory |
 | `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | Custom download URL for binary |
 | `CLOAKBROWSER_AUTO_UPDATE` | `true` | Set to `false` to disable background update checks |
-| `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Set to `true` to skip SHA-256 verification after download |
+| `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | Only applies to a custom `CLOAKBROWSER_DOWNLOAD_URL`: set to `true` to skip its checksum check. Signature verification on the official download path is mandatory and cannot be skipped. |
 | `CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS` | `5` | Max seconds for GeoIP resolution before continuing without it |
 | `CLOAKBROWSER_WIDEVINE_CDM` | — | Path to a sideloaded `WidevineCdm` directory (overrides auto-detection next to the binary). See [Widevine / DRM](#widevine--drm) |
 | `CLOAKBROWSER_WIDEVINE` | `1` | Set to `0` to disable automatic Widevine hint-file seeding for persistent contexts |
@@ -641,9 +665,11 @@ The binary is **stealthy by default** — no flags needed. It auto-generates a r
 The binary detects its platform at compile time — a macOS binary reports as macOS with Apple GPU, a Linux binary reports as Linux with NVIDIA GPU. The **wrapper** overrides this on Linux by passing `--fingerprint-platform=windows`, so sessions appear as Windows desktops (more common fingerprint, harder to cluster). Use `--fingerprint-platform` for cross-platform spoofing when running the binary directly.
 
 > **Tip: Use a fixed seed when revisiting the same site.** A random seed makes every session look like a different device — which can be suspicious when hitting the same site repeatedly from the same IP. For reCAPTCHA v3 Enterprise and similar scoring systems, a fixed seed produces a consistent fingerprint across sessions, making you look like a returning visitor:
+>
 > ```python
 > browser = launch(args=["--fingerprint=12345"])
 > ```
+>
 > ```javascript
 > const browser = await launch({ args: ['--fingerprint=12345'] });
 > ```
@@ -682,6 +708,7 @@ Supported by the binary but **not set by default** — pass via `args` to custom
 | `--fingerprint-storage-quota` | Override storage quota in MB — affects `storage.estimate()`, `storageBuckets`, and legacy webkit APIs. Auto-normalized when `--fingerprint` is set |
 | `--fingerprint-taskbar-height` | Override taskbar height (binary defaults: Win=48, Mac=95, Linux=0) |
 | `--fingerprint-fonts-dir` | Path to directory containing target-platform fonts (see [Font Setup on Linux](#font-setup-on-linux)) |
+| `--fingerprint-windows-font-metrics` | Align font metrics with the Windows platform when spoofing Windows on Linux — used in the [FingerprintJS config](#detected-by-fingerprintjs). Requires Windows fonts installed (see [Font Setup on Linux](#font-setup-on-linux)); no effect without them |
 | `--fingerprint-webrtc-ip` | WebRTC ICE candidate IP replacement. Use `auto` to resolve from proxy exit IP (makes an HTTP call through the proxy), or pass an explicit IP. Auto-injected when `geoip=True` |
 | `--fingerprint-noise=false` | Disable noise injection (canvas, WebGL, audio, client rects) while keeping the deterministic fingerprint seed active |
 | `--enable-blink-features=FakeShadowRoot` | Access closed shadow DOM elements |
@@ -736,6 +763,7 @@ browser = launch(args=[
 ## Examples
 
 **Python** — see [`examples/`](examples/):
+
 - [`basic.py`](examples/basic.py) — Launch and load a page
 - [`persistent_context.py`](examples/persistent_context.py) — Persistent profile with cookie/localStorage persistence
 - [`recaptcha_score.py`](examples/recaptcha_score.py) — Check your reCAPTCHA v3 score
@@ -743,6 +771,7 @@ browser = launch(args=[
 - [`fingerprint_scan_test.py`](examples/fingerprint_scan_test.py) — Test against fingerprint-scan.com and CreepJS
 
 **JavaScript** — see [`js/examples/`](js/examples/):
+
 - [`basic-playwright.ts`](js/examples/basic-playwright.ts) — Playwright launch and load
 - [`basic-puppeteer.ts`](js/examples/basic-puppeteer.ts) — Puppeteer launch and load
 - [`stealth-test.ts`](js/examples/stealth-test.ts) — Run against 6 detection sites
@@ -808,6 +837,8 @@ The wrapper auto-downloads the correct binary for your platform.
 
 Pre-built image on Docker Hub — no install, no setup.
 
+> **Pro:** the image ships with the free binary. Set `CLOAKBROWSER_LICENSE_KEY` (e.g. `-e CLOAKBROWSER_LICENSE_KEY=cb_xxx`, or in Compose) and the latest binary downloads at runtime.
+
 ### Quick test
 
 ```bash
@@ -1065,6 +1096,7 @@ FingerprintJS (`demo.fingerprint.com/playground`) checks multiple signals. Each
 |-----------|-------|-----|
 | **`nodriver` / bad bot** | IP reputation or missing flags | Residential proxy + config below |
 | **Browser tampering** | Noise injection detected by ML | `--fingerprint-noise=false` |
+| **Browser tampering** (fonts) | Font metrics don't match the spoofed Windows platform | `--fingerprint-windows-font-metrics` (requires Windows fonts installed) |
 | **Virtual machine** | Screen dimensions don't match viewport | `--fingerprint-screen-width/height` matching viewport |
 | **Incognito** | Storage quota normalized to ~500MB | Expected tradeoff — see below |
 
@@ -1077,8 +1109,7 @@ browser = launch(
     geoip=True,
     args=[
         "--fingerprint-noise=false",          # prevents tampering detection
-        "--fingerprint-screen-width=1920",    # match your viewport
-        "--fingerprint-screen-height=1080",
+        "--fingerprint-windows-font-metrics", # align font metrics (requires Windows fonts)
     ],
 )
 ```
@@ -1090,8 +1121,7 @@ const browser = await launch({
     geoip: true,
     args: [
         '--fingerprint-noise=false',
-        '--fingerprint-screen-width=1920',
-        '--fingerprint-screen-height=1080',
+        '--fingerprint-windows-font-metrics',  // align font metrics (requires Windows fonts)
     ],
 });
 ```
@@ -1151,6 +1181,7 @@ For stateless/ephemeral use cases, `launch(args=["--disable-http2"])` forces HTT
 ### Something not working? Make sure you're on the latest version
 
 Older versions may use outdated stealth args or download an older binary:
+
 ```bash
 pip install -U cloakbrowser    # Python
 npm install cloakbrowser@latest # JavaScript
@@ -1162,6 +1193,7 @@ docker pull cloakhq/cloakbrowser:latest  # Docker
 ### Binary download fails / timeout
 
 Set a custom download URL or use a local binary:
+
 ```bash
 export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome
 ```
@@ -1171,11 +1203,13 @@ export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome
 ### New update broke something? Roll back to the previous version
 
 Install a specific wrapper version to downgrade both the wrapper and the binary it downloads:
+
 ```bash
 pip install cloakbrowser==0.3.21              # Python
 npm install cloakbrowser@0.3.21               # JavaScript
 docker pull cloakhq/cloakbrowser:0.3.21       # Docker
 ```
+
 Each wrapper version pins its own binary version, so downgrading the wrapper automatically gets you the matching binary on next launch.
 
 ---
@@ -1183,6 +1217,7 @@ Each wrapper version pins its own binary version, so downgrading the wrapper aut
 ### macOS: "App is damaged" or Gatekeeper blocks launch
 
 The binary is ad-hoc signed. macOS quarantines downloaded files. Run once to clear it:
+
 ```bash
 xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app
 ```
@@ -1192,6 +1227,7 @@ xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app
 ### "playwright install" vs CloakBrowser binary
 
 You do NOT need `playwright install chromium`. CloakBrowser downloads its own binary. You only need Playwright's system deps:
+
 ```bash
 playwright install-deps chromium
 ```
@@ -1240,16 +1276,18 @@ await new Promise(r => setTimeout(r, 3000));
 ```
 
 Other tips for maximizing reCAPTCHA scores:
-- **Try the Patchright backend** — suppresses additional CDP automation signals at the Playwright protocol layer. Install with `pip install cloakbrowser[patchright]`, then use `launch(backend="patchright")` or set `CLOAKBROWSER_BACKEND=patchright` globally. Note: Patchright breaks proxy auth and `add_init_script` — only use it if you're still seeing low scores after trying the steps above
+
 - **Use Playwright, not Puppeteer** — Puppeteer sends more CDP protocol traffic that reCAPTCHA detects ([details](#puppeteer))
 - **Use residential proxies** — datacenter IPs are flagged by IP reputation, not browser fingerprint
 - **Spend 15+ seconds on the page** before triggering reCAPTCHA — short visits score lower
 - **Space out requests** — back-to-back `grecaptcha.execute()` calls from the same session get penalized. Wait 30+ seconds between pages with reCAPTCHA
 - **Use a fixed fingerprint seed** for consistent device identity across sessions (see [Fingerprint Management](#fingerprint-management))
 - **Use `page.type()` instead of `page.fill()`** for form filling — `fill()` sets values directly without keyboard events, which reCAPTCHA's behavioral analysis flags. `type()` with a delay simulates real keystrokes:
+
   ```python
   page.type("#email", "user@example.com", delay=50)
   ```
+
 - **Minimize `page.evaluate()` calls** before the reCAPTCHA check fires — each one sends CDP traffic
 
 ## FAQ
@@ -1257,6 +1295,15 @@ Other tips for maximizing reCAPTCHA scores:
 **Q: Is this legal?**
 A: CloakBrowser is a browser built on open-source Chromium. We do not condone illegal use. Automating systems without authorization, credential stuffing, and account creation abuse are expressly prohibited. See [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md) for full terms.
 
+**Q: Is CloakBrowser free?**
+A: The wrapper (Python + JS) is MIT and free forever. The binary uses a delayed free-release model: the previous Chromium major version (currently v146) is free on GitHub Releases with unlimited sessions; the latest major version is for [Pro subscribers](https://cloakbrowser.dev). Each new major release rolls the prior major version down to free.
+
+**Q: Do I need a license key for the free version?**
+A: No. The free binary downloads automatically with no key. A license key only unlocks the latest (Pro) binary.
+
+**Q: What happens if I cancel Pro?**
+A: Your subscription stays active until the end of the current billing period — cancelling doesn't cut you off immediately. After it ends, the wrapper stops pulling new Pro versions and falls back to the free binary on its next license check (cached ~24h). You just stop getting new versions.
+
 **Q: How is this different from Camoufox?**
 A: Camoufox patches Firefox. We patch Chromium. Chromium means native Playwright support, larger ecosystem, and TLS fingerprints that match real Chrome. Camoufox returned in early 2026 but is in unstable beta — CloakBrowser is production-ready.
 
@@ -1285,11 +1332,11 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` or `proxy="socks5://user:pass@
 - 📦 **PyPI** — [pypi.org/project/cloakbrowser](https://pypi.org/project/cloakbrowser/)
 - 📦 **npm** — [npmjs.com/package/cloakbrowser](https://www.npmjs.com/package/cloakbrowser)
 - ☕ **Support** — [ko-fi.com/cloakhq](https://ko-fi.com/cloakhq)
-- 📧 **Contact** — cloakhq@pm.me
+- 📧 **Contact** — <cloakhq@pm.me>
 
 ## Security
 
-All releases are signed for supply chain verification.
+The wrapper automatically verifies every binary download against a pinned Ed25519 signature on the published checksums before extraction — a compromised mirror cannot serve a tampered or downgraded binary. Releases are additionally signed for manual supply chain verification:
 
 ```bash
 # Verify GPG signature (binary release tag)
@@ -1309,7 +1356,10 @@ cosign verify \
 ## License
 
 - **Wrapper code** (this repository) — MIT. See [LICENSE](https://github.com/CloakHQ/CloakBrowser/blob/main/LICENSE).
-- **CloakBrowser binary** (compiled Chromium) — free to use, no redistribution. See [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md).
+- **CloakBrowser binary** (compiled Chromium):
+  - **v146 and earlier** — free for personal and commercial use, no redistribution (OEM/SaaS license required to serve third parties).
+  - **v148+ (latest)** — requires an active [CloakBrowser Pro](https://cloakbrowser.dev) subscription to download.
+  - See [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md) for full terms.
 
 ## Contributing
 

cloakbrowser/__init__.py

@@ -14,6 +14,7 @@ Usage:
 from .browser import launch, launch_async, launch_context, launch_context_async, launch_persistent_context, launch_persistent_context_async, ProxySettings, build_args, maybe_resolve_geoip
 from .config import CHROMIUM_VERSION, get_default_stealth_args
 from .download import binary_info, check_for_update, clear_cache, ensure_binary
+from .license import LicenseInfo, validate_license
 from ._version import __version__
 
 # Human-like behavioral layer (optional)
@@ -44,6 +45,8 @@ __all__ = [
     "build_args",
     "maybe_resolve_geoip",
     "ProxySettings",
+    "validate_license",
+    "LicenseInfo",
     "HumanConfig",
     "resolve_human_config",
     "__version__",

cloakbrowser/_version.py

@@ -1 +1 @@
-__version__ = "0.3.32"
+__version__ = "0.4.0"

cloakbrowser/browser.py

@@ -31,6 +31,79 @@ logger = logging.getLogger("cloakbrowser")
 _VIEWPORT_UNSET = object()
 
 
+def _default_no_viewport(browser: Any) -> None:
+    """Default ``new_page()``/``new_context()`` to ``no_viewport=True``.
+
+    ``launch()`` returns a raw Playwright ``Browser``; a bare ``browser.new_page()``
+    would otherwise inherit Playwright's emulated 1280x720 viewport, producing
+    ``outerWidth < innerWidth`` — a physically impossible window (bot tell). We wrap
+    the two factory methods so pages track the real OS window instead. ``setdefault``
+    only: an explicit ``viewport`` or ``no_viewport`` from the caller is never
+    overridden (Playwright rejects passing both). Applied for headed launches only.
+    Composes under humanize's ``patch_browser`` (apply this first).
+    """
+    orig_new_context = browser.new_context
+    orig_new_page = browser.new_page
+
+    def _patched_new_context(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return orig_new_context(**kwargs)
+
+    def _patched_new_page(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return orig_new_page(**kwargs)
+
+    browser.new_context = _patched_new_context
+    browser.new_page = _patched_new_page
+
+
+def _default_no_viewport_async(browser: Any) -> None:
+    """Async variant of :func:`_default_no_viewport`."""
+    orig_new_context = browser.new_context
+    orig_new_page = browser.new_page
+
+    async def _patched_new_context(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return await orig_new_context(**kwargs)
+
+    async def _patched_new_page(**kwargs: Any) -> Any:
+        if "viewport" not in kwargs:
+            kwargs.setdefault("no_viewport", True)
+        return await orig_new_page(**kwargs)
+
+    browser.new_context = _patched_new_context
+    browser.new_page = _patched_new_page
+
+
+def _resolve_context_viewport(viewport: Any, headless: bool) -> dict[str, Any]:
+    """Return the viewport kwarg for a context.
+
+    Headed: no emulated viewport so the page tracks the real window (CDP viewport
+    emulation forces outerWidth < innerWidth = a physically impossible window =
+    bot tell). Headless: a fixed ``DEFAULT_VIEWPORT`` stays coherent (outer == inner)
+    and keeps dimensions deterministic. Explicit ``viewport`` / ``None`` honored.
+    """
+    if viewport is _VIEWPORT_UNSET:
+        return {"viewport": DEFAULT_VIEWPORT} if headless else {"no_viewport": True}
+    if viewport is None:
+        return {"no_viewport": True}
+    return {"viewport": viewport}
+
+
+def _drop_conflicting_viewport(context_kwargs: dict[str, Any], kwargs: dict[str, Any]) -> None:
+    """Playwright rejects passing both ``viewport`` and ``no_viewport``. ``viewport`` is a
+    named parameter (never in ``**kwargs``), so the only conflict is a caller passing
+    ``no_viewport`` via ``**kwargs`` alongside an explicit ``viewport`` — the explicit
+    ``no_viewport`` wins; drop the viewport so Playwright doesn't error.
+    """
+    if "no_viewport" in kwargs and "viewport" in context_kwargs:
+        logger.debug("Both viewport and no_viewport requested; no_viewport (kwargs) wins")
+        context_kwargs.pop("viewport", None)
+
+
 def _resolve_timezone(timezone: str | None, kwargs: dict[str, Any]) -> str | None:
     """Accept both timezone and timezone_id — either works, no warning."""
     if "timezone_id" in kwargs:
@@ -41,6 +114,15 @@ def _resolve_timezone(timezone: str | None, kwargs: dict[str, Any]) -> str | Non
     return timezone
 
 
+def _check_removed_kwargs(kwargs: dict[str, Any]) -> None:
+    """Raise a clear error for removed parameters that now fall into **kwargs."""
+    if "backend" in kwargs:
+        raise TypeError(
+            "The 'backend' parameter has been removed — patchright is no longer "
+            "supported and stock Playwright is the only backend. Remove the argument."
+        )
+
+
 class _ProxySettingsRequired(TypedDict):
     server: str
 
@@ -61,11 +143,11 @@ def launch(
     timezone: str | None = None,
     locale: str | None = None,
     geoip: bool = False,
-    backend: str | None = None,
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
     extension_paths: list[str] | None = None,
+    license_key: str | None = None,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth Chromium browser. Returns a Playwright Browser object.
@@ -86,10 +168,6 @@ def launch(
             Requires ``pip install cloakbrowser[geoip]``. Downloads ~70 MB
             GeoLite2-City database on first use.  Explicit timezone/locale
             always override geoip results.
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
-            Patchright suppresses CDP signals (helps reCAPTCHA v3 Enterprise)
-            but breaks proxy auth and add_init_script.
-            Override globally with CLOAKBROWSER_BACKEND env var.
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
@@ -106,9 +184,11 @@ def launch(
         >>> print(page.title())
         >>> browser.close()
     """
-    sync_playwright = _import_sync_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
 
-    binary_path = ensure_binary()
+    from playwright.sync_api import sync_playwright
+
+    binary_path = ensure_binary(license_key=license_key)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
     proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy)
     args = _resolve_webrtc_args(args, proxy)
@@ -141,6 +221,12 @@ def launch(
 
     browser.close = _close_with_cleanup
 
+    # Headed: default new_page()/new_context() to no_viewport so the page tracks the
+    # real window (avoids the impossible-window tell). Headless keeps Playwright's
+    # default viewport (coherent there). Apply before humanize so the wraps compose.
+    if not headless:
+        _default_no_viewport(browser)
+
     # Human-like behavioral patching
     if humanize:
         from .human import patch_browser
@@ -159,11 +245,11 @@ async def launch_async(  # noqa: C901
     timezone: str | None = None,
     locale: str | None = None,
     geoip: bool = False,
-    backend: str | None = None,
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
     extension_paths: list[str] | None = None,
+    license_key: str | None = None,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch(). Returns a Playwright Browser object.
@@ -177,7 +263,6 @@ async def launch_async(  # noqa: C901
         timezone: IANA timezone (e.g. 'America/New_York'). Sets --fingerprint-timezone binary flag.
         locale: BCP 47 locale (e.g. 'en-US'). Sets --lang binary flag.
         geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
@@ -199,9 +284,11 @@ async def launch_async(  # noqa: C901
         >>>
         >>> asyncio.run(main())
     """
-    async_playwright = _import_async_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
 
-    binary_path = ensure_binary()
+    from playwright.async_api import async_playwright
+
+    binary_path = ensure_binary(license_key=license_key)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
     proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy)
     args = _resolve_webrtc_args(args, proxy)
@@ -233,6 +320,10 @@ async def launch_async(  # noqa: C901
 
     browser.close = _close_with_cleanup
 
+    # Headed: default new_page()/new_context() to no_viewport (see launch()).
+    if not headless:
+        _default_no_viewport_async(browser)
+
     # Human-like behavioral patching (async variant)
     if humanize:
         from .human import patch_browser_async
@@ -255,11 +346,11 @@ def launch_persistent_context(
     timezone: str | None = None,
     color_scheme: Literal["light", "dark", "no-preference"] | None = None,
     geoip: bool = False,
-    backend: str | None = None,
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
     extension_paths: list[str] | None = None,
+    license_key: str | None = None,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth browser with a persistent profile and return a BrowserContext.
@@ -286,7 +377,6 @@ def launch_persistent_context(
             Default: None (uses Chromium default, which is 'light').
         geoip: Auto-detect timezone/locale from proxy IP (default False).
             Requires ``pip install cloakbrowser[geoip]``.
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
@@ -303,11 +393,13 @@ def launch_persistent_context(
         >>> page.goto("https://protected-site.com")
         >>> ctx.close()  # Profile is saved; re-use path next run to restore state.
     """
-    sync_playwright = _import_sync_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.sync_api import sync_playwright
 
     timezone = _resolve_timezone(timezone, kwargs)
 
-    binary_path = ensure_binary()
+    binary_path = ensure_binary(license_key=license_key)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
     proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy)
     args = _resolve_webrtc_args(args, proxy)
@@ -327,15 +419,11 @@ def launch_persistent_context(
     context_kwargs: dict[str, Any] = {}
     if user_agent:
         context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
     if color_scheme:
         context_kwargs["color_scheme"] = color_scheme
     context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)
 
     seed_widevine_hint(user_data_dir, binary_path)
 
@@ -383,11 +471,11 @@ async def launch_persistent_context_async(
     timezone: str | None = None,
     color_scheme: Literal["light", "dark", "no-preference"] | None = None,
     geoip: bool = False,
-    backend: str | None = None,
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
     extension_paths: list[str] | None = None,
+    license_key: str | None = None,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch_persistent_context().
@@ -411,7 +499,6 @@ async def launch_persistent_context_async(
         timezone: IANA timezone (e.g. 'America/New_York').
         color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
         geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
@@ -433,11 +520,13 @@ async def launch_persistent_context_async(
         >>>
         >>> asyncio.run(main())
     """
-    async_playwright = _import_async_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.async_api import async_playwright
 
     timezone = _resolve_timezone(timezone, kwargs)
 
-    binary_path = ensure_binary()
+    binary_path = ensure_binary(license_key=license_key)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
     proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy)
     args = _resolve_webrtc_args(args, proxy)
@@ -457,15 +546,11 @@ async def launch_persistent_context_async(
     context_kwargs: dict[str, Any] = {}
     if user_agent:
         context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
     if color_scheme:
         context_kwargs["color_scheme"] = color_scheme
     context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)
 
     seed_widevine_hint(user_data_dir, binary_path)
 
@@ -512,11 +597,11 @@ def launch_context(
     timezone: str | None = None,
     color_scheme: Literal["light", "dark", "no-preference"] | None = None,
     geoip: bool = False,
-    backend: str | None = None,
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
     extension_paths: list[str] | None = None,
+    license_key: str | None = None,
     **kwargs: Any,
 ) -> Any:
     """Launch stealth browser and return a BrowserContext with common options pre-set.
@@ -538,7 +623,6 @@ def launch_context(
         color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
             Default: None (uses Chromium default, which is 'light').
         geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
@@ -547,6 +631,8 @@ def launch_context(
     Returns:
         Playwright BrowserContext object.
     """
+    _check_removed_kwargs(kwargs)
+
     timezone = _resolve_timezone(timezone, kwargs)
 
     # Resolve geoip BEFORE launch() to avoid double-resolution and ensure
@@ -560,20 +646,17 @@ def launch_context(
     # so it applies to ALL contexts, not just the default one.
     # locale and timezone are set via binary flags only — no CDP emulation.
     browser = launch(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                     timezone=timezone, locale=locale, backend=backend, extension_paths=extension_paths)
+                     timezone=timezone, locale=locale, extension_paths=extension_paths,
+                     license_key=license_key)
 
     context_kwargs: dict[str, Any] = {}
     if user_agent:
         context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
     if color_scheme:
         context_kwargs["color_scheme"] = color_scheme
     context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)
 
     try:
         context = browser.new_context(**context_kwargs)
@@ -613,11 +696,11 @@ async def launch_context_async(
     timezone: str | None = None,
     color_scheme: Literal["light", "dark", "no-preference"] | None = None,
     geoip: bool = False,
-    backend: str | None = None,
     humanize: bool = False,
     human_preset: HumanPreset = "default",
     human_config: HumanConfigOverrides | None = None,
     extension_paths: list[str] | None = None,
+    license_key: str | None = None,
     **kwargs: Any,
 ) -> Any:
     """Async version of launch_context().
@@ -640,7 +723,6 @@ async def launch_context_async(
         timezone: IANA timezone (e.g. 'America/New_York').
         color_scheme: Color scheme preference — 'light', 'dark', or 'no-preference'.
         geoip: Auto-detect timezone/locale from proxy IP (default False).
-        backend: Playwright backend — 'playwright' (default) or 'patchright'.
         humanize: Enable human-like mouse, keyboard, scroll behavior (default False).
         human_preset: Humanize preset — 'default' or 'careful' (default 'default').
         human_config: Custom humanize config mapping to override preset values.
@@ -668,6 +750,8 @@ async def launch_context_async(
         >>>
         >>> asyncio.run(main())
     """
+    _check_removed_kwargs(kwargs)
+
     timezone = _resolve_timezone(timezone, kwargs)
 
     # Resolve geoip BEFORE launch_async() to avoid double-resolution and ensure
@@ -680,20 +764,17 @@ async def launch_context_async(
     # so it applies to ALL contexts, not just the default one.
     # locale and timezone are set via binary flags only — no CDP emulation.
     browser = await launch_async(headless=headless, proxy=proxy, args=args, stealth_args=stealth_args,
-                                 timezone=timezone, locale=locale, backend=backend, extension_paths=extension_paths)
+                                 timezone=timezone, locale=locale, extension_paths=extension_paths,
+                                 license_key=license_key)
 
     context_kwargs: dict[str, Any] = {}
     if user_agent:
         context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
     if color_scheme:
         context_kwargs["color_scheme"] = color_scheme
     context_kwargs.update(kwargs)
+    _drop_conflicting_viewport(context_kwargs, kwargs)
 
     # Catch BaseException (not just Exception) so that asyncio.CancelledError
     # triggers browser cleanup — otherwise the underlying Chromium process
@@ -728,47 +809,6 @@ async def launch_context_async(
     return context
 
 
-# ---------------------------------------------------------------------------
-# Backend resolution
-# ---------------------------------------------------------------------------
-
-
-def _resolve_backend(backend: str | None) -> str:
-    """Resolve backend: param > env var > default ('playwright')."""
-    b = backend or os.environ.get("CLOAKBROWSER_BACKEND", "playwright")
-    if b not in ("playwright", "patchright"):
-        raise ValueError(f"Unknown backend '{b}'. Use 'playwright' or 'patchright'.")
-    return b
-
-
-def _import_sync_playwright(backend: str):
-    """Import sync_playwright from the resolved backend."""
-    if backend == "patchright":
-        try:
-            from patchright.sync_api import sync_playwright
-        except ModuleNotFoundError:
-            raise ModuleNotFoundError(
-                "patchright is not installed. Install it with: pip install cloakbrowser[patchright]"
-            ) from None
-        return sync_playwright
-    from playwright.sync_api import sync_playwright
-    return sync_playwright
-
-
-def _import_async_playwright(backend: str):
-    """Import async_playwright from the resolved backend."""
-    if backend == "patchright":
-        try:
-            from patchright.async_api import async_playwright
-        except ModuleNotFoundError:
-            raise ModuleNotFoundError(
-                "patchright is not installed. Install it with: pip install cloakbrowser[patchright]"
-            ) from None
-        return async_playwright
-    from playwright.async_api import async_playwright
-    return async_playwright
-
-
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------

cloakbrowser/config.py

@@ -25,6 +25,19 @@ PLATFORM_CHROMIUM_VERSIONS: dict[str, str] = {
     "windows-x64": "146.0.7680.177.5",
 }
 
+# ---------------------------------------------------------------------------
+# Ed25519 public keys for verifying downloaded binaries.
+#
+# Each release publishes SHA256SUMS and a detached signature SHA256SUMS.sig.
+# The wrapper verifies that signature against the keys below before trusting
+# any hash in the manifest, so the download origin alone cannot certify a
+# tampered binary. Values are base64 of the 32-byte raw public key. Multiple
+# entries are accepted to allow key rotation.
+# ---------------------------------------------------------------------------
+BINARY_SIGNING_PUBKEYS: list[str] = [
+    "MKFKwIhUcKWq5xTuNA0Ovg99njcDEcEJvmWYYhApvaU=",
+]
+
 # ---------------------------------------------------------------------------
 # Playwright default args to suppress — these leak automation signals.
 # --enable-automation: exposes navigator.webdriver = true
@@ -55,16 +68,19 @@ def get_default_stealth_args() -> list[str]:
         # Tell the fingerprint patches we're on macOS so GPU/UA match natively
         return base + ["--fingerprint-platform=macos"]
 
-    # Linux/Windows: Windows fingerprint profile
-    # Hardware concurrency, device memory, screen, window size, and GPU are
-    # auto-generated by the binary from the seed (v14+).
+    # Linux/Windows: Windows fingerprint profile.
+    # Screen and window size come from the real display, not this flag (verified:
+    # identical across seeds), so the wrapper must not emulate a viewport on top in
+    # headed mode — that would break outerWidth >= innerWidth coherence.
     return base + ["--fingerprint-platform=windows"]
 
 
 # ---------------------------------------------------------------------------
-# Default viewport — realistic maximized Chrome on 1080p Windows
-# screen=1920x1080, availHeight=1032 (minus 48px taskbar, binary default),
-# innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks)
+# Default viewport — used for HEADLESS only (headed launches use no_viewport so
+# the page tracks the real window). Headless has no window chrome, so a fixed
+# viewport stays coherent (outer == inner) and gives deterministic dimensions.
+# Models a maximized Chrome on 1080p Windows: screen=1920x1080,
+# innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks).
 # ---------------------------------------------------------------------------
 DEFAULT_VIEWPORT = {"width": 1920, "height": 947}
 
@@ -118,15 +134,16 @@ def get_cache_dir() -> Path:
     return Path.home() / ".cloakbrowser"
 
 
-def get_binary_dir(version: str | None = None) -> Path:
+def get_binary_dir(version: str | None = None, pro: bool = False) -> Path:
     """Return the directory for a Chromium version binary."""
     v = version or get_chromium_version()
-    return get_cache_dir() / f"chromium-{v}"
+    suffix = "-pro" if pro else ""
+    return get_cache_dir() / f"chromium-{v}{suffix}"
 
 
-def get_binary_path(version: str | None = None) -> Path:
+def get_binary_path(version: str | None = None, pro: bool = False) -> Path:
     """Return the expected path to the chrome executable."""
-    binary_dir = get_binary_dir(version)
+    binary_dir = get_binary_dir(version, pro=pro)
 
     if platform.system() == "Darwin":
         # macOS: Chromium.app bundle
@@ -156,15 +173,30 @@ def check_platform_available() -> None:
         )
 
 
-def get_effective_version() -> str:
+def get_effective_version(pro: bool = False) -> str:
     """Return the best available version: auto-updated if available, else platform default.
 
     Reads a platform-scoped marker file from the cache directory.
     Returns the platform's hardcoded version if no update has been downloaded.
+    When pro=True, reads from the Pro-specific marker files.
     """
     base = get_chromium_version()
-    # Try platform-scoped marker first, fall back to legacy marker for upgrades from <0.3.0
     cache = get_cache_dir()
+
+    if pro:
+        marker = cache / f"latest_pro_version_{get_platform_tag()}"
+        if marker.exists():
+            try:
+                version = marker.read_text().strip()
+                if version:
+                    binary = get_binary_path(version, pro=True)
+                    if binary.exists():
+                        return version
+            except (ValueError, OSError):
+                pass
+        return base
+
+    # Free tier: try platform-scoped marker first, fall back to legacy marker
     for name in (f"latest_version_{get_platform_tag()}", "latest_version"):
         marker = cache / name
         if marker.exists():

cloakbrowser/download.py

@@ -23,6 +23,7 @@ import httpx
 
 from ._version import __version__ as _wrapper_version
 from .config import (
+    BINARY_SIGNING_PUBKEYS,
     CHROMIUM_VERSION,
     DOWNLOAD_BASE_URL,
     GITHUB_API_URL,
@@ -44,6 +45,17 @@ from .config import (
 
 logger = logging.getLogger("cloakbrowser")
 
+
+class BinaryVerificationError(RuntimeError):
+    """A downloaded binary could not be authenticated (bad/missing signature,
+    version mismatch, or checksum failure).
+
+    Distinct from transient download/network errors: a verification failure is
+    a tampering signal and MUST surface, never silently fall back to another
+    binary. The Pro routing in ensure_binary re-raises this rather than
+    downgrading to the free tier.
+    """
+
 # Timeout for download (large binary, allow 10 min)
 DOWNLOAD_TIMEOUT = httpx.Timeout(connect=10.0, read=60.0, write=10.0, pool=10.0)
 
@@ -70,11 +82,14 @@ def _show_welcome() -> None:
         pass
 
 
-def ensure_binary() -> str:
+def ensure_binary(license_key: str | None = None) -> str:
     """Ensure the stealth Chromium binary is available. Download if needed.
 
     Returns the path to the chrome executable as a string.
 
+    Args:
+        license_key: Pro license key. Also reads from CLOAKBROWSER_LICENSE_KEY env var.
+
     Set CLOAKBROWSER_BINARY_PATH to skip download and use a local build.
     """
     # Check for local override first
@@ -88,6 +103,39 @@ def ensure_binary() -> str:
         logger.info("Using local binary override: %s", local_override)
         return str(path)
 
+    # Pro license key check (custom download URL overrides Pro path)
+    from .license import resolve_license_key, validate_license
+
+    key = resolve_license_key(license_key)
+    if os.environ.get("CLOAKBROWSER_DOWNLOAD_URL"):
+        key = None
+
+    if key:
+        info = validate_license(key)
+        if info and info.valid:
+            # A valid license is entitled to Pro, so Pro failures surface loudly
+            # rather than silently substituting the older free binary. (A blip
+            # during a routine update never reaches here: _ensure_pro_binary
+            # returns the cached Pro binary and updates in the background.)
+            try:
+                return _ensure_pro_binary(key)
+            except BinaryVerificationError:
+                # Authenticity could not be confirmed — surface verbatim.
+                raise
+            except Exception as e:
+                # Transient failure with no cached Pro binary to use — surface a
+                # clear error rather than silently downloading the free binary.
+                raise RuntimeError(
+                    f"Pro binary unavailable: {e}. Your license is valid but the "
+                    f"Pro binary could not be downloaded right now. Retry in a "
+                    f"moment. To use the free binary instead, unset "
+                    f"CLOAKBROWSER_LICENSE_KEY."
+                ) from e
+        elif info:
+            logger.warning("License validation failed (plan=%s), using free tier", info.plan)
+        else:
+            logger.warning("License validation unavailable, using free tier")
+
     # Fail fast if no binary available for this platform
     check_platform_available()
 
@@ -162,8 +210,10 @@ def _download_and_extract(version: str | None = None) -> None:
             )
             _download_file(fallback_url, tmp_path)
 
-        # Verify checksum before extraction
-        if os.environ.get("CLOAKBROWSER_SKIP_CHECKSUM", "").lower() != "true":
+        # Verify the download before extraction. On the official path this is a
+        # mandatory, non-bypassable Ed25519 signature check (see
+        # _verify_download_checksum); the skip flag only applies to custom
+        # self-hosted CLOAKBROWSER_DOWNLOAD_URL setups.
         _verify_download_checksum(tmp_path, version)
 
         _extract_archive(tmp_path, binary_dir, binary_path)
@@ -173,23 +223,308 @@ def _download_and_extract(version: str | None = None) -> None:
         tmp_path.unlink(missing_ok=True)
 
 
+def _ensure_pro_binary(license_key: str) -> str:
+    """Ensure the Pro binary is downloaded and cached. Returns the binary path."""
+    from .license import get_pro_latest_version
+
+    effective = get_effective_version(pro=True)
+    binary_path = get_binary_path(effective, pro=True)
+
+    if binary_path.exists() and _is_executable(binary_path):
+        logger.debug("Pro binary found in cache: %s (version %s)", binary_path, effective)
+        _show_welcome()
+        _maybe_trigger_pro_update_check(license_key)
+        return str(binary_path)
+
+    version = get_pro_latest_version()
+    if not version:
+        raise RuntimeError("Could not determine latest Pro version from server")
+
+    binary_path = get_binary_path(version, pro=True)
+    if binary_path.exists() and _is_executable(binary_path):
+        logger.debug("Pro binary found in cache: %s (version %s)", binary_path, version)
+        _show_welcome()
+        return str(binary_path)
+
+    logger.info("Downloading Pro Chromium %s for %s...", version, get_platform_tag())
+    _download_pro_binary(version, license_key)
+
+    binary_path = get_binary_path(version, pro=True)
+    if not binary_path.exists():
+        raise RuntimeError(
+            f"Pro download completed but binary not found at: {binary_path}"
+        )
+
+    # Write Pro version marker (atomic)
+    marker = get_cache_dir() / f"latest_pro_version_{get_platform_tag()}"
+    try:
+        tmp = marker.with_suffix(".tmp")
+        tmp.write_text(version)
+        os.replace(str(tmp), str(marker))
+    except OSError:
+        pass
+
+    _show_welcome()
+    return str(binary_path)
+
+
+def _download_pro_binary(version: str, license_key: str) -> None:
+    """Download a Pro binary from cloakbrowser.dev with license key auth.
+
+    Requests the explicit version so the served archive matches the signed
+    manifest verified in _verify_pro_download.
+    """
+    download_url = f"{DOWNLOAD_BASE_URL}/api/download/{version}"
+    binary_dir = get_binary_dir(version, pro=True)
+    binary_path = get_binary_path(version, pro=True)
+    platform_tag = get_platform_tag()
+
+    binary_dir.parent.mkdir(parents=True, exist_ok=True)
+
+    with tempfile.NamedTemporaryFile(suffix=get_archive_ext(), delete=False) as tmp:
+        tmp_path = Path(tmp.name)
+
+    try:
+        _download_file(
+            download_url,
+            tmp_path,
+            headers={
+                "Authorization": f"Bearer {license_key}",
+                "X-Platform": platform_tag,
+            },
+        )
+
+        # Pro binaries come from cloakbrowser.dev — the same origin as free
+        # downloads — so the M1 attack the Ed25519 signature defends against
+        # applies equally. Verify with the same non-bypassable signature check;
+        # CLOAKBROWSER_SKIP_CHECKSUM does NOT bypass it (parity with the
+        # official free path).
+        _verify_pro_download(tmp_path, version)
+
+        _extract_archive(tmp_path, binary_dir, binary_path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def _verify_pro_download(file_path: Path, version: str) -> None:
+    """Verify a Pro archive with the same non-bypassable Ed25519 signature check
+    as official free downloads.
+
+    Pro binaries are served from cloakbrowser.dev (same origin as the free
+    tier), so a tampered same-origin SHA256SUMS could otherwise certify a
+    tampered binary (M1, #308). Fetch the Pro SHA256SUMS + detached
+    SHA256SUMS.sig, verify the signature against the pinned keys FIRST, bind the
+    manifest to the requested version, then verify the archive's SHA-256.
+
+    An invalid signature, checksum, or version mismatch raises
+    BinaryVerificationError (a tampering signal the router surfaces verbatim);
+    CLOAKBROWSER_SKIP_CHECKSUM cannot bypass it. A failed manifest FETCH is
+    transient — nothing was validated — and raises a plain RuntimeError. A
+    valid-license user is never silently downgraded to the free binary.
+    """
+    base = f"{DOWNLOAD_BASE_URL}/releases/pro/chromium-v{version}"
+    try:
+        manifest_resp = httpx.get(
+            f"{base}/SHA256SUMS", follow_redirects=True, timeout=10.0
+        )
+        manifest_resp.raise_for_status()
+        sig_resp = httpx.get(
+            f"{base}/SHA256SUMS.sig", follow_redirects=True, timeout=10.0
+        )
+        sig_resp.raise_for_status()
+    except Exception as exc:
+        # Fetch failure is transient, not tampering — raise a plain RuntimeError
+        # (the router reports it as "unavailable, retry") rather than a
+        # BinaryVerificationError (which it surfaces as a tampering signal).
+        raise RuntimeError(
+            f"Could not fetch the signed SHA256SUMS for Pro {version} ({exc})"
+        )
+
+    manifest_bytes = manifest_resp.content
+    # _verify_signature / _verify_checksum raise plain RuntimeError; convert to
+    # BinaryVerificationError so the Pro router treats them as tampering signals
+    # (re-raise) rather than transient failures (fall back to free).
+    try:
+        _verify_signature(manifest_bytes, sig_resp.content)
+    except RuntimeError as exc:
+        raise BinaryVerificationError(str(exc)) from exc
+    manifest_text = manifest_bytes.decode("utf-8")
+
+    # Version binding: same forced-downgrade defense as the official path.
+    declared = _parse_manifest_version(manifest_text)
+    if declared != version:
+        raise BinaryVerificationError(
+            f"Version mismatch in signed Pro SHA256SUMS: requested {version}, "
+            f"manifest declares {declared or 'none'}. Refusing (possible downgrade)."
+        )
+
+    tarball_name = get_archive_name()
+    expected = _parse_checksums(manifest_text).get(tarball_name)
+    if expected is None:
+        raise BinaryVerificationError(
+            f"Signature-verified Pro SHA256SUMS has no entry for {tarball_name} — "
+            f"cannot confirm binary integrity."
+        )
+    try:
+        _verify_checksum(file_path, expected)
+    except RuntimeError as exc:
+        raise BinaryVerificationError(str(exc)) from exc
+
+
 def _verify_download_checksum(file_path: Path, version: str | None = None) -> None:
-    """Fetch SHA256SUMS and verify the downloaded file. Warn if unavailable, fail on mismatch."""
-    checksums = _fetch_checksums(version)
+    """Verify the downloaded archive's integrity and authenticity.
+
+    Official path (cloakbrowser.dev / GitHub Releases): fetch SHA256SUMS plus
+    its detached Ed25519 signature SHA256SUMS.sig, verify the signature against
+    the pinned public keys FIRST, then verify the archive's SHA-256 against the
+    now-authenticated manifest. Mandatory and non-bypassable — a same-origin
+    manifest can no longer certify a tampered binary (#308).
+
+    Custom self-hosted path (CLOAKBROWSER_DOWNLOAD_URL set): the pinned keys do
+    not apply to a third-party server, so fall back to the plain same-origin
+    SHA256SUMS check, which CLOAKBROWSER_SKIP_CHECKSUM may bypass.
+    """
     tarball_name = get_archive_name()
 
+    if os.environ.get("CLOAKBROWSER_DOWNLOAD_URL"):
+        # Self-hosted mirror: signature scheme does not apply. Preserve the
+        # legacy same-origin checksum behavior, skippable as before.
+        if os.environ.get("CLOAKBROWSER_SKIP_CHECKSUM", "").lower() == "true":
+            logger.warning(
+                "CLOAKBROWSER_SKIP_CHECKSUM set — skipping verification for custom download URL"
+            )
+            return
+        checksums = _fetch_checksums(version)
         if checksums is None:
-        logger.warning("SHA256SUMS not available for this release — skipping checksum verification")
+            logger.warning(
+                "SHA256SUMS not available from custom URL — skipping checksum verification"
+            )
             return
-
         expected = checksums.get(tarball_name)
         if expected is None:
-        logger.warning("SHA256SUMS found but no entry for %s — skipping verification", tarball_name)
+            logger.warning(
+                "SHA256SUMS found but no entry for %s — skipping verification", tarball_name
+            )
+            return
+        _verify_checksum(file_path, expected)
         return
 
+    # Official path: signature is the trust root and is non-bypassable.
+    manifest = _fetch_signed_manifest(version)
+    if manifest is None:
+        raise RuntimeError(
+            "Could not fetch a signed SHA256SUMS (SHA256SUMS + SHA256SUMS.sig) "
+            "for this release — refusing to use an unverified binary. "
+            "Retry, or report at https://github.com/CloakHQ/cloakbrowser/issues"
+        )
+    manifest_bytes, sig_bytes = manifest
+    _verify_signature(manifest_bytes, sig_bytes)
+    manifest_text = manifest_bytes.decode("utf-8")
+
+    # Version binding: the signed manifest must declare the version we asked for.
+    # The signature proves "we made this manifest", not "this is the version you
+    # requested" — without this check a mirror could serve a genuinely-signed
+    # older release in place of the requested one (forced downgrade).
+    requested = version or get_chromium_version()
+    declared = _parse_manifest_version(manifest_text)
+    if declared != requested:
+        raise RuntimeError(
+            f"Version mismatch in signed SHA256SUMS: requested {requested}, "
+            f"manifest declares {declared or 'none'}. Refusing (possible downgrade)."
+        )
+
+    checksums = _parse_checksums(manifest_text)
+    expected = checksums.get(tarball_name)
+    if expected is None:
+        raise RuntimeError(
+            f"Signature-verified SHA256SUMS has no entry for {tarball_name} — "
+            f"cannot confirm binary integrity."
+        )
     _verify_checksum(file_path, expected)
 
 
+def _parse_manifest_version(text: str) -> str | None:
+    """Read the 'version=<v>' line from a signed manifest. None if absent.
+
+    The line has no internal whitespace so older wrappers' SHA256SUMS parsers
+    ignore it (they only accept '<hash>  <filename>' lines).
+    """
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("version="):
+            return line[len("version="):].strip()
+    return None
+
+
+def _fetch_signed_manifest(version: str | None = None) -> tuple[bytes, bytes] | None:
+    """Fetch (SHA256SUMS, SHA256SUMS.sig) raw bytes for a version, or None.
+
+    Both files are fetched from the SAME origin so the signature always matches
+    the exact manifest bytes it certifies. The primary origin is tried first,
+    then the GitHub Releases mirror. follow_redirects mirrors _fetch_checksums:
+    cloakbrowser.dev 301-redirects /chromium-v* to GitHub Releases.
+    """
+    v = version or get_chromium_version()
+    bases = [
+        f"{DOWNLOAD_BASE_URL}/chromium-v{v}",
+        f"{GITHUB_DOWNLOAD_BASE_URL}/chromium-v{v}",
+    ]
+    for base in bases:
+        try:
+            manifest_resp = httpx.get(
+                f"{base}/SHA256SUMS", follow_redirects=True, timeout=10.0
+            )
+            manifest_resp.raise_for_status()
+            sig_resp = httpx.get(
+                f"{base}/SHA256SUMS.sig", follow_redirects=True, timeout=10.0
+            )
+            sig_resp.raise_for_status()
+            return manifest_resp.content, sig_resp.content
+        except Exception:
+            continue
+    return None
+
+
+def _verify_signature(manifest_bytes: bytes, sig_b64: bytes) -> None:
+    """Verify a detached Ed25519 signature over the raw manifest bytes.
+
+    sig_b64 is the base64 of the 64-byte raw signature. Tries each pinned key
+    in BINARY_SIGNING_PUBKEYS; succeeds if any validates. Raises RuntimeError
+    if the signature is malformed or no pinned key validates it.
+    """
+    import base64
+
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    try:
+        signature = base64.b64decode(sig_b64.strip(), validate=True)
+    except Exception as exc:
+        raise RuntimeError(f"Malformed SHA256SUMS.sig (not valid base64): {exc}")
+
+    for pubkey_b64 in BINARY_SIGNING_PUBKEYS:
+        try:
+            pub = Ed25519PublicKey.from_public_bytes(base64.b64decode(pubkey_b64))
+        except Exception:
+            # Skip an unparseable pinned key (e.g. the placeholder) rather than
+            # aborting — another pinned key may still validate.
+            continue
+        try:
+            pub.verify(signature, manifest_bytes)
+            logger.info("SHA256SUMS signature verified: Ed25519 OK")
+            return
+        except Exception:
+            # InvalidSignature, or a malformed/wrong-length signature that makes
+            # verify raise something else — either way this key didn't match,
+            # so try the next pinned key (and ultimately fail closed below).
+            continue
+
+    raise RuntimeError(
+        "SHA256SUMS signature verification failed — no pinned key validated the "
+        "manifest. The binary's authenticity could not be confirmed. "
+        "Report at https://github.com/CloakHQ/cloakbrowser/issues"
+    )
+
+
 def _fetch_checksums(version: str | None = None) -> dict[str, str] | None:
     """Fetch SHA256SUMS file for a version. Returns {filename: hash} or None."""
     v = version or get_chromium_version()
@@ -211,17 +546,22 @@ def _fetch_checksums(version: str | None = None) -> dict[str, str] | None:
 
 
 def _parse_checksums(text: str) -> dict[str, str]:
-    """Parse SHA256SUMS format: 'hash  filename' per line."""
+    """Parse SHA256SUMS format: '<64-hex sha256>  filename' per line.
+
+    Only lines whose first token is a 64-character hex digest are accepted
+    (matches the JS parser); blank lines, the version= line, and any other
+    junk are ignored.
+    """
     result = {}
     for line in text.strip().splitlines():
-        line = line.strip()
-        if not line:
+        parts = line.strip().split(None, 1)
+        if len(parts) != 2:
             continue
-        parts = line.split(None, 1)
-        if len(parts) == 2:
         hash_val, filename = parts
-            filename = filename.lstrip("*")
-            result[filename] = hash_val.lower()
+        hash_val = hash_val.lower()
+        if len(hash_val) != 64 or any(c not in "0123456789abcdef" for c in hash_val):
+            continue
+        result[filename.lstrip("*")] = hash_val
     return result
 
 
@@ -243,11 +583,11 @@ def _verify_checksum(file_path: Path, expected_hash: str) -> None:
     logger.info("Checksum verified: SHA-256 OK")
 
 
-def _download_file(url: str, dest: Path) -> None:
+def _download_file(url: str, dest: Path, headers: dict[str, str] | None = None) -> None:
     """Download a file with progress logging."""
     logger.info("Downloading from %s", url)
 
-    with httpx.stream("GET", url, follow_redirects=True, timeout=DOWNLOAD_TIMEOUT) as response:
+    with httpx.stream("GET", url, follow_redirects=True, timeout=DOWNLOAD_TIMEOUT, headers=headers or {}) as response:
         response.raise_for_status()
 
         total = int(response.headers.get("content-length", 0))
@@ -401,17 +741,34 @@ def clear_cache() -> None:
 
 
 def binary_info() -> dict:
-    """Return info about the current binary installation."""
+    """Return info about the current binary installation.
+
+    tier reflects what is actually installed on disk, not merely whether a
+    license is cached — a cached license with no Pro binary downloaded yet is
+    still effectively running the free binary, and the active key may differ
+    from the cached one.
+    """
+    # Prefer Pro only if a Pro binary actually exists on disk.
+    pro_version = get_effective_version(pro=True)
+    pro_path = get_binary_path(pro_version, pro=True)
+    pro = pro_path.exists() and _is_executable(pro_path)
+
+    if pro:
+        effective = pro_version
+        binary_path = pro_path
+    else:
         effective = get_effective_version()
         binary_path = get_binary_path(effective)
+    download_url = f"{DOWNLOAD_BASE_URL}/api/download/latest" if pro else get_download_url(effective)
     return {
         "version": effective,
+        "tier": "pro" if pro else "free",
         "bundled_version": CHROMIUM_VERSION,
         "platform": get_platform_tag(),
         "binary_path": str(binary_path),
         "installed": binary_path.exists(),
-        "cache_dir": str(get_binary_dir(effective)),
-        "download_url": get_download_url(effective),
+        "cache_dir": str(get_binary_dir(effective, pro=pro)),
+        "download_url": download_url,
     }
 
 
@@ -576,3 +933,43 @@ def _maybe_trigger_update_check() -> None:
         return
     t = threading.Thread(target=_check_and_download_update, daemon=True)
     t.start()
+
+
+def _maybe_trigger_pro_update_check(license_key: str) -> None:
+    """Fire-and-forget Pro binary update check in a daemon thread."""
+    check_file = get_cache_dir() / ".last_pro_update_check"
+    if check_file.exists():
+        try:
+            last_check = float(check_file.read_text().strip())
+            if time.time() - last_check < UPDATE_CHECK_INTERVAL:
+                return
+        except (ValueError, OSError):
+            pass
+
+    def _check():
+        try:
+            from .license import get_pro_latest_version
+
+            check_file.parent.mkdir(parents=True, exist_ok=True)
+            check_file.write_text(str(time.time()))
+
+            latest = get_pro_latest_version()
+            if not latest:
+                return
+
+            if get_binary_path(latest, pro=True).exists():
+                return
+
+            logger.info("Newer Pro binary available: %s. Downloading in background...", latest)
+            _download_pro_binary(latest, license_key)
+
+            marker = get_cache_dir() / f"latest_pro_version_{get_platform_tag()}"
+            tmp = marker.with_suffix(".tmp")
+            tmp.write_text(latest)
+            os.replace(str(tmp), str(marker))
+            logger.info("Pro background update complete: %s ready. Will use on next launch.", latest)
+        except Exception:
+            logger.debug("Pro background update failed", exc_info=True)
+
+    t = threading.Thread(target=_check, daemon=True)
+    t.start()

cloakbrowser/license.py

@@ -0,0 +1,188 @@
+"""License validation and caching for CloakBrowser Pro.
+
+Handles license key resolution, server validation with local caching,
+and Pro version checks.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from .config import get_cache_dir
+
+logger = logging.getLogger("cloakbrowser")
+
+VALIDATE_URL = "https://cloakbrowser.dev/api/license/validate"
+PRO_VERSION_URL = "https://cloakbrowser.dev/api/download/version"
+
+LICENSE_CACHE_TTL = 86400  # 24 hours
+PRO_VERSION_CHECK_INTERVAL = 3600  # 1 hour
+
+
+@dataclass
+class LicenseInfo:
+    valid: bool
+    plan: str
+    expires: str | None
+
+
+def resolve_license_key(license_key: str | None = None) -> str | None:
+    """Resolve the license key: explicit param > env var > file > None."""
+    if license_key and license_key.strip():
+        return license_key.strip()
+    env_key = os.environ.get("CLOAKBROWSER_LICENSE_KEY", "").strip()
+    if env_key:
+        return env_key
+    key_file = get_cache_dir() / "license.key"
+    try:
+        content = key_file.read_text().strip()
+        if content:
+            return content
+    except OSError:
+        pass
+    return None
+
+
+def validate_license(license_key: str) -> LicenseInfo | None:
+    """Validate a license key with the CloakBrowser server.
+
+    Checks a local file cache first (24h TTL). Falls back to stale
+    cache if the server is unreachable.
+
+    Returns LicenseInfo if validation succeeded, None on total failure.
+    """
+    cache_path = get_cache_dir() / ".license_cache"
+    key_sha = hashlib.sha256(license_key.encode()).hexdigest()
+
+    cached = _read_cache(cache_path, key_sha)
+    if cached:
+        return cached
+
+    try:
+        resp = httpx.post(
+            VALIDATE_URL,
+            json={"license_key": license_key},
+            timeout=10.0,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        info = LicenseInfo(
+            valid=data.get("valid", False),
+            plan=data.get("plan", "solo"),
+            expires=data.get("expires"),
+        )
+
+        if info.valid:
+            _write_cache(cache_path, key_sha, info)
+        return info
+
+    except Exception as e:
+        logger.warning("License validation request failed: %s", e)
+
+        stale = _read_cache(cache_path, key_sha, ignore_ttl=True)
+        if stale:
+            logger.warning("Using cached license validation (server unreachable)")
+            return stale
+
+        return None
+
+
+def get_pro_latest_version() -> str | None:
+    """Get the latest Pro binary version from the server.
+
+    Rate-limited to 1 call per hour via a marker file.
+    """
+    marker = get_cache_dir() / ".last_pro_version_check"
+
+    if marker.exists():
+        try:
+            age = time.time() - marker.stat().st_mtime
+            if age < PRO_VERSION_CHECK_INTERVAL:
+                content = marker.read_text().strip()
+                return content if content else None
+        except OSError:
+            pass
+
+    try:
+        resp = httpx.get(PRO_VERSION_URL, timeout=10.0)
+        resp.raise_for_status()
+        version = resp.json().get("version")
+        if not version:
+            return None
+
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        tmp = marker.with_suffix(".tmp")
+        tmp.write_text(version)
+        os.replace(str(tmp), str(marker))
+        return version
+
+    except Exception as e:
+        logger.debug("Pro version check failed: %s", e)
+        return None
+
+
+def _read_cache(
+    cache_path: Path, key_sha: str, ignore_ttl: bool = False
+) -> LicenseInfo | None:
+    """Read cached license validation if it exists and is fresh."""
+    try:
+        if not cache_path.exists():
+            return None
+
+        data = json.loads(cache_path.read_text())
+
+        if data.get("key_sha256") != key_sha:
+            return None
+
+        if not ignore_ttl:
+            validated_at = data.get("validated_at", 0)
+            if time.time() - validated_at > LICENSE_CACHE_TTL:
+                return None
+
+        expires = data.get("expires")
+        if expires:
+            try:
+                from datetime import datetime, timezone
+                exp_dt = datetime.fromisoformat(expires)
+                if exp_dt.tzinfo is None:
+                    exp_dt = exp_dt.replace(tzinfo=timezone.utc)
+                if exp_dt < datetime.now(timezone.utc):
+                    return LicenseInfo(valid=False, plan=data.get("plan", "solo"), expires=expires)
+            except (ValueError, TypeError):
+                pass
+
+        return LicenseInfo(
+            valid=data.get("valid", False),
+            plan=data.get("plan", "solo"),
+            expires=expires,
+        )
+    except (json.JSONDecodeError, OSError, KeyError, TypeError):
+        # TypeError: a corrupted cache with a non-numeric validated_at. Treat any
+        # unreadable cache as absent rather than crashing the caller.
+        return None
+
+
+def _write_cache(cache_path: Path, key_sha: str, info: LicenseInfo) -> None:
+    """Write license validation result to local cache (atomic via tmp+rename)."""
+    try:
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = cache_path.with_suffix(".tmp")
+        tmp_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": info.valid,
+            "plan": info.plan,
+            "expires": info.expires,
+            "validated_at": time.time(),
+        }))
+        os.replace(str(tmp_path), str(cache_path))
+    except OSError as e:
+        logger.debug("Failed to write license cache: %s", e)

js/README.md

@@ -231,11 +231,30 @@ const page = await browser.newPage();
 
 | Platform | Chromium | Patches | Status |
 |---|---|---|---|
-| Linux x86_64 | 145 | 48 | ✅ Latest |
-| Linux arm64 (RPi, Graviton) | 145 | 48 | ✅ Latest |
-| macOS arm64 (Apple Silicon) | 145 | 26 | ✅ Latest |
-| macOS x86_64 (Intel) | 145 | 26 | ✅ Latest |
-| Windows x86_64 | 145 | 48 | ✅ Latest |
+| Linux x86_64 | 146 | 58 | ✅ Latest |
+| Linux arm64 (RPi, Graviton) | 146 | 58 | ✅ |
+| macOS arm64 (Apple Silicon) | 145 | 26 | ✅ |
+| macOS x86_64 (Intel) | 145 | 26 | ✅ |
+| Windows x86_64 | 146 | 58 | ✅ Latest |
+
+## CloakBrowser Pro
+
+The wrapper (Python + JS) is MIT, free forever. The binary uses a delayed
+free-release model:
+
+- **Free (v146)** — free forever on [GitHub Releases](https://github.com/CloakHQ/cloakbrowser/releases). Unlimited sessions. Works today, goes stale as detection evolves.
+- **Pro (latest, v148)** — the newest patches and Chromium upgrades first, so the [test results](#test-results) stay green as anti-bot systems change. Linux + Windows (macOS coming).
+
+Anti-bot detection updates constantly — an older binary degrades within weeks.
+Pro keeps you on the build that's actively maintained against it.
+
+Activate with your license key (env var, `licenseKey` option, or `~/.cloakbrowser/license.key`):
+
+```bash
+export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx
+```
+
+Pro plans → **[cloakbrowser.dev](https://cloakbrowser.dev)**
 
 ## Requirements
 
@@ -294,13 +313,13 @@ Other tips for maximizing reCAPTCHA scores:
 When auto-update downloads a newer binary, the previous version stays in `~/.cloakbrowser/`. Point `CLOAKBROWSER_BINARY_PATH` to the older cached binary:
 ```bash
 # Linux
-export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.159.2/chrome
+export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-146.0.7680.177.4/chrome
 
 # macOS
 export CLOAKBROWSER_BINARY_PATH=~/.cloakbrowser/chromium-145.0.7632.109.2/Chromium.app/Contents/MacOS/Chromium
 
 # Windows
-set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-145.0.7632.159.7\chrome.exe
+set CLOAKBROWSER_BINARY_PATH=%USERPROFILE%\.cloakbrowser\chromium-146.0.7680.177.4\chrome.exe
 ```
 
 ## Links

js/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cloakbrowser",
-  "version": "0.3.32",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cloakbrowser",
-      "version": "0.3.32",
+      "version": "0.4.0",
       "license": "MIT",
       "dependencies": {
         "tar": "^7.0.0"

js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloakbrowser",
-  "version": "0.3.32",
+  "version": "0.4.0",
   "description": "Stealth Chromium that passes every bot detection test. Drop-in Playwright/Puppeteer replacement with source-level fingerprint patches.",
   "type": "module",
   "main": "dist/index.js",

js/src/config.ts

@@ -37,6 +37,19 @@ export const PLATFORM_CHROMIUM_VERSIONS: Record<string, string> = {
   "windows-x64": "146.0.7680.177.5",
 };
 
+// ---------------------------------------------------------------------------
+// Ed25519 public keys for verifying downloaded binaries.
+//
+// Each release publishes SHA256SUMS and a detached signature SHA256SUMS.sig.
+// The wrapper verifies that signature against the keys below before trusting
+// any hash in the manifest, so the download origin alone cannot certify a
+// tampered binary. Values are base64 of the 32-byte raw public key. Multiple
+// entries are accepted to allow key rotation. Keep in parity with config.py.
+// ---------------------------------------------------------------------------
+export const BINARY_SIGNING_PUBKEYS: string[] = [
+  "MKFKwIhUcKWq5xTuNA0Ovg99njcDEcEJvmWYYhApvaU=",
+];
+
 // ---------------------------------------------------------------------------
 // Platform detection
 // ---------------------------------------------------------------------------
@@ -86,12 +99,13 @@ export function getCacheDir(): string {
   return path.join(os.homedir(), ".cloakbrowser");
 }
 
-export function getBinaryDir(version?: string): string {
-  return path.join(getCacheDir(), `chromium-${version || getChromiumVersion()}`);
+export function getBinaryDir(version?: string, pro = false): string {
+  const suffix = pro ? "-pro" : "";
+  return path.join(getCacheDir(), `chromium-${version || getChromiumVersion()}${suffix}`);
 }
 
-export function getBinaryPath(version?: string): string {
-  const binaryDir = getBinaryDir(version);
+export function getBinaryPath(version?: string, pro = false): string {
+  const binaryDir = getBinaryDir(version, pro);
   if (process.platform === "darwin") {
     return path.join(binaryDir, "Chromium.app", "Contents", "MacOS", "Chromium");
   }
@@ -145,10 +159,29 @@ export function getFallbackDownloadUrl(version?: string): string {
   return `${GITHUB_DOWNLOAD_BASE_URL}/chromium-v${v}/${getArchiveName()}`;
 }
 
-export function getEffectiveVersion(): string {
+export function getEffectiveVersion(pro = false): string {
   const base = getChromiumVersion();
   const cacheDir = getCacheDir();
-  // Try platform-scoped marker first, fall back to legacy marker for upgrades from <0.3.0
+
+  if (pro) {
+    const marker = path.join(cacheDir, `latest_pro_version_${getPlatformTag()}`);
+    try {
+      if (fs.existsSync(marker)) {
+        const version = fs.readFileSync(marker, "utf-8").trim();
+        if (version) {
+          const binary = getBinaryPath(version, true);
+          if (fs.existsSync(binary)) {
+            return version;
+          }
+        }
+      }
+    } catch {
+      // Marker unreadable
+    }
+    return base;
+  }
+
+  // Free tier: try platform-scoped marker first, fall back to legacy marker for upgrades from <0.3.0
   for (const name of [`latest_version_${getPlatformTag()}`, "latest_version"]) {
     const marker = path.join(cacheDir, name);
     try {
@@ -200,9 +233,11 @@ export const IGNORE_DEFAULT_ARGS = ["--enable-automation", "--enable-unsafe-swif
 // ---------------------------------------------------------------------------
 // Default stealth arguments
 // ---------------------------------------------------------------------------
-// Default viewport — realistic maximized Chrome on 1080p Windows
-// screen=1920x1080, availHeight=1032 (minus 48px taskbar, binary default),
-// innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks)
+// Default viewport — used for HEADLESS only (headed launches use no viewport so
+// the page tracks the real window). Headless has no window chrome, so a fixed
+// viewport stays coherent (outer == inner) and gives deterministic dimensions.
+// Models a maximized Chrome on 1080p Windows: screen=1920x1080,
+// innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks).
 export const DEFAULT_VIEWPORT = { width: 1920, height: 947 };
 
 export function getDefaultStealthArgs(): string[] {
@@ -219,8 +254,9 @@ export function getDefaultStealthArgs(): string[] {
     return [...base, "--fingerprint-platform=macos"];
   }
 
-  // Linux/Windows: spoof as Windows desktop
-  // Hardware concurrency, device memory, screen, window size, and GPU are
-  // auto-generated by the binary from the seed (v14+).
+  // Linux/Windows: spoof as Windows desktop.
+  // Screen and window size come from the real display, not this flag (verified:
+  // identical across seeds), so the wrapper must not emulate a viewport on top in
+  // headed mode — that would break outerWidth >= innerWidth coherence.
   return [...base, "--fingerprint-platform=windows"];
 }

js/src/download.ts

@@ -5,7 +5,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { pipeline } from "node:stream/promises";
@@ -14,6 +14,8 @@ import { extract as tarExtract } from "tar";
 
 import type { BinaryInfo } from "./types.js";
 import {
+  BINARY_SIGNING_PUBKEYS,
+  CHROMIUM_VERSION,
   DOWNLOAD_BASE_URL,
   GITHUB_API_URL,
   GITHUB_DOWNLOAD_BASE_URL,
@@ -32,10 +34,25 @@ import {
   getPlatformTag,
   versionNewer,
 } from "./config.js";
+import { resolveLicenseKey, validateLicense, getProLatestVersion } from "./license.js";
 
 const DOWNLOAD_TIMEOUT_MS = 600_000; // 10 minutes
 const UPDATE_CHECK_INTERVAL_MS = 3_600_000; // 1 hour
 
+/**
+ * A downloaded binary could not be authenticated (bad/missing signature,
+ * version mismatch, or checksum failure). Distinct from transient
+ * download/network errors: a verification failure is a tampering signal and
+ * MUST surface, never silently fall back to another binary. The Pro routing in
+ * ensureBinary re-throws this rather than downgrading to the free tier.
+ */
+export class BinaryVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BinaryVerificationError";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -44,7 +61,7 @@ const UPDATE_CHECK_INTERVAL_MS = 3_600_000; // 1 hour
  * Ensure the stealth Chromium binary is available. Download if needed.
  * Returns the path to the chrome executable.
  */
-export async function ensureBinary(): Promise<string> {
+export async function ensureBinary(licenseKey?: string): Promise<string> {
   // Check for local override
   const localOverride = getLocalBinaryOverride();
   if (localOverride) {
@@ -57,6 +74,37 @@ export async function ensureBinary(): Promise<string> {
     return localOverride;
   }
 
+  // Pro license key check (custom download URL overrides Pro path)
+  const key = resolveLicenseKey(licenseKey);
+  const effectiveKey = process.env.CLOAKBROWSER_DOWNLOAD_URL ? undefined : key;
+  if (effectiveKey) {
+    const info = await validateLicense(effectiveKey);
+    if (info?.valid) {
+      // A valid license is entitled to Pro, so Pro failures surface loudly
+      // rather than silently substituting the older free binary. (A blip during
+      // a routine update never reaches here: ensureProBinary returns the cached
+      // Pro binary and updates in the background.)
+      try {
+        return await ensureProBinary(effectiveKey);
+      } catch (e) {
+        // Authenticity could not be confirmed — surface verbatim.
+        if (e instanceof BinaryVerificationError) throw e;
+        // Transient failure with no cached Pro binary to use — surface a clear
+        // error rather than silently downloading the free binary.
+        throw new Error(
+          `Pro binary unavailable: ${e}. Your license is valid but the Pro ` +
+            `binary could not be downloaded right now. Retry in a moment. To use ` +
+            `the free binary instead, unset CLOAKBROWSER_LICENSE_KEY.`,
+          { cause: e }
+        );
+      }
+    } else if (info) {
+      console.log(`[cloakbrowser] License validation failed (plan=${info.plan}), using free tier`);
+    } else {
+      console.log("[cloakbrowser] License validation unavailable, using free tier");
+    }
+  }
+
   // Fail fast if no binary available for this platform
   checkPlatformAvailable();
 
@@ -108,17 +156,31 @@ export function clearCache(): void {
   }
 }
 
-/** Return info about the current binary installation. */
+/**
+ * Return info about the current binary installation.
+ *
+ * tier reflects what is actually installed on disk, not merely whether a license
+ * is cached — a cached license with no Pro binary downloaded yet is still
+ * effectively running the free binary, and the active key may differ from the
+ * cached one.
+ */
 export function binaryInfo(): BinaryInfo {
-  const effective = getEffectiveVersion();
-  const binaryPath = getBinaryPath(effective);
+  // Prefer Pro only if a Pro binary actually exists on disk.
+  const proVersion = getEffectiveVersion(true);
+  const proPath = getBinaryPath(proVersion, true);
+  const isPro = fs.existsSync(proPath) && isExecutable(proPath);
+
+  const effective = isPro ? proVersion : getEffectiveVersion(false);
+  const binaryPath = isPro ? proPath : getBinaryPath(effective, false);
   return {
     version: effective,
+    bundledVersion: CHROMIUM_VERSION,
+    tier: isPro ? "pro" : "free",
     platform: getPlatformTag(),
     binaryPath,
     installed: fs.existsSync(binaryPath),
-    cacheDir: getBinaryDir(effective),
-    downloadUrl: getDownloadUrl(effective),
+    cacheDir: getBinaryDir(effective, isPro),
+    downloadUrl: isPro ? `${DOWNLOAD_BASE_URL}/api/download/latest` : getDownloadUrl(effective),
   };
 }
 
@@ -195,10 +257,11 @@ async function downloadAndExtract(version?: string): Promise<void> {
       await downloadFile(fallbackUrl, tmpPath);
     }
 
-    // Verify checksum before extraction
-    if (process.env.CLOAKBROWSER_SKIP_CHECKSUM?.toLowerCase() !== "true") {
+    // Verify the download before extraction. On the official path this is a
+    // mandatory, non-bypassable Ed25519 signature check (see
+    // verifyDownloadChecksum); the skip flag only applies to custom
+    // self-hosted CLOAKBROWSER_DOWNLOAD_URL setups.
     await verifyDownloadChecksum(tmpPath, version);
-    }
 
     await extractArchive(tmpPath, binaryDir, binaryPath);
     showWelcome();
@@ -210,22 +273,176 @@ async function downloadAndExtract(version?: string): Promise<void> {
   }
 }
 
-async function verifyDownloadChecksum(filePath: string, version?: string): Promise<void> {
-  const checksums = await fetchChecksums(version);
+/** @internal Exported for testing only. */
+export async function verifyDownloadChecksum(filePath: string, version?: string): Promise<void> {
   const tarballName = getArchiveName();
 
+  if (process.env.CLOAKBROWSER_DOWNLOAD_URL) {
+    // Self-hosted mirror: the pinned signature keys do not apply to a
+    // third-party server. Preserve the legacy same-origin checksum behavior,
+    // skippable via CLOAKBROWSER_SKIP_CHECKSUM.
+    if (process.env.CLOAKBROWSER_SKIP_CHECKSUM?.toLowerCase() === "true") {
+      console.warn(
+        "[cloakbrowser] CLOAKBROWSER_SKIP_CHECKSUM set — skipping verification for custom download URL"
+      );
+      return;
+    }
+    const checksums = await fetchChecksums(version);
     if (!checksums) {
-    console.warn("[cloakbrowser] SHA256SUMS not available for this release — skipping checksum verification");
+      console.warn(
+        "[cloakbrowser] SHA256SUMS not available from custom URL — skipping checksum verification"
+      );
+      return;
+    }
+    const expectedCustom = checksums.get(tarballName);
+    if (!expectedCustom) {
+      console.warn(
+        `[cloakbrowser] SHA256SUMS found but no entry for ${tarballName} — skipping verification`
+      );
+      return;
+    }
+    await verifyChecksum(filePath, expectedCustom);
     return;
   }
 
+  // Official path: signature is the trust root and is non-bypassable.
+  const manifest = await fetchSignedManifest(version);
+  if (!manifest) {
+    throw new Error(
+      "Could not fetch a signed SHA256SUMS (SHA256SUMS + SHA256SUMS.sig) for " +
+        "this release — refusing to use an unverified binary. " +
+        "Retry, or report at https://github.com/CloakHQ/cloakbrowser/issues"
+    );
+  }
+  const { manifestBytes, sigBytes } = manifest;
+  verifySignature(manifestBytes, sigBytes);
+  const manifestText = new TextDecoder().decode(manifestBytes);
+
+  // Version binding: the signed manifest must declare the version we asked for.
+  // The signature proves "we made this manifest", not "this is the version you
+  // requested" — without this check a mirror could serve a genuinely-signed
+  // older release in place of the requested one (forced downgrade).
+  const requested = version || getChromiumVersion();
+  const declared = parseManifestVersion(manifestText);
+  if (declared !== requested) {
+    throw new Error(
+      `Version mismatch in signed SHA256SUMS: requested ${requested}, ` +
+        `manifest declares ${declared ?? "none"}. Refusing (possible downgrade).`
+    );
+  }
+
+  const checksums = parseChecksums(manifestText);
   const expected = checksums.get(tarballName);
   if (!expected) {
-    console.warn(`[cloakbrowser] SHA256SUMS found but no entry for ${tarballName} — skipping verification`);
-    return;
+    throw new Error(
+      `Signature-verified SHA256SUMS has no entry for ${tarballName} — ` +
+        `cannot confirm binary integrity.`
+    );
+  }
+  await verifyChecksum(filePath, expected);
 }
 
-  await verifyChecksum(filePath, expected);
+/**
+ * Read the 'version=<v>' line from a signed manifest. null if absent.
+ * The line has no internal whitespace so older wrappers' SHA256SUMS parsers
+ * ignore it (they only accept '<hash>  <filename>' lines).
+ * @internal Exported for testing only.
+ */
+export function parseManifestVersion(text: string): string | null {
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line.startsWith("version=")) {
+      return line.slice("version=".length).trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Fetch (SHA256SUMS, SHA256SUMS.sig) raw bytes for a version, or null.
+ * Both files come from the SAME origin so the signature always matches the
+ * exact manifest bytes it certifies. Primary origin first, then GitHub mirror.
+ * @internal Exported for testing only.
+ */
+export async function fetchSignedManifest(
+  version?: string
+): Promise<{ manifestBytes: Uint8Array; sigBytes: Uint8Array } | null> {
+  const v = version || getChromiumVersion();
+  const bases = [
+    `${DOWNLOAD_BASE_URL}/chromium-v${v}`,
+    `${GITHUB_DOWNLOAD_BASE_URL}/chromium-v${v}`,
+  ];
+  for (const base of bases) {
+    try {
+      const manifestResp = await fetch(`${base}/SHA256SUMS`, {
+        redirect: "follow",
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!manifestResp.ok) continue;
+      const sigResp = await fetch(`${base}/SHA256SUMS.sig`, {
+        redirect: "follow",
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!sigResp.ok) continue;
+      return {
+        manifestBytes: new Uint8Array(await manifestResp.arrayBuffer()),
+        sigBytes: new Uint8Array(await sigResp.arrayBuffer()),
+      };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Verify a detached Ed25519 signature over the raw manifest bytes.
+ * sigB64Bytes is the (base64-text) content of SHA256SUMS.sig. Tries each pinned
+ * key; succeeds if any validates. Throws if malformed or no key validates.
+ * @internal Exported for testing only.
+ */
+export function verifySignature(manifestBytes: Uint8Array, sigB64Bytes: Uint8Array): void {
+  // Node's Buffer.from(...,"base64") is lenient — it silently drops invalid
+  // characters instead of throwing. Validate by canonical round-trip so a
+  // malformed .sig is reported as such (parity with Python's
+  // base64.b64decode(validate=True)).
+  const sigText = new TextDecoder().decode(sigB64Bytes).trim();
+  const signature = Buffer.from(sigText, "base64");
+  if (signature.toString("base64") !== sigText) {
+    throw new Error("Malformed SHA256SUMS.sig (not valid base64)");
+  }
+
+  for (const pubkeyB64 of BINARY_SIGNING_PUBKEYS) {
+    let keyObject;
+    try {
+      // Build an Ed25519 public key from raw 32 bytes via JWK import.
+      const x = Buffer.from(pubkeyB64, "base64").toString("base64url");
+      keyObject = createPublicKey({
+        key: { kty: "OKP", crv: "Ed25519", x },
+        format: "jwk",
+      });
+    } catch {
+      // Skip an unparseable pinned key (e.g. the placeholder); another may validate.
+      continue;
+    }
+    try {
+      if (cryptoVerify(null, manifestBytes, keyObject, signature)) {
+        console.log("[cloakbrowser] SHA256SUMS signature verified: Ed25519 OK");
+        return;
+      }
+    } catch {
+      // A malformed/wrong-length signature can make verify throw rather than
+      // return false — treat it as a non-match and try the next pinned key
+      // (parity with Python's try/except around pub.verify), failing closed below.
+      continue;
+    }
+  }
+
+  throw new Error(
+    "SHA256SUMS signature verification failed — no pinned key validated the " +
+      "manifest. The binary's authenticity could not be confirmed. " +
+      "Report at https://github.com/CloakHQ/cloakbrowser/issues"
+  );
 }
 
 /** @internal Exported for testing only. */
@@ -287,7 +504,7 @@ async function verifyChecksum(filePath: string, expectedHash: string): Promise<v
   console.log("[cloakbrowser] Checksum verified: SHA-256 OK");
 }
 
-async function downloadFile(url: string, dest: string): Promise<void> {
+async function downloadFile(url: string, dest: string, headers?: Record<string, string>): Promise<void> {
   console.log(`[cloakbrowser] Downloading from ${url}`);
 
   const controller = new AbortController();
@@ -300,6 +517,7 @@ async function downloadFile(url: string, dest: string): Promise<void> {
     const response = await fetch(url, {
       signal: controller.signal,
       redirect: "follow",
+      ...(headers ? { headers } : {}),
     });
 
     if (!response.ok) {
@@ -363,6 +581,168 @@ async function downloadFile(url: string, dest: string): Promise<void> {
 }
 
 
+// ---------------------------------------------------------------------------
+// Pro binary download
+// ---------------------------------------------------------------------------
+
+async function ensureProBinary(licenseKey: string): Promise<string> {
+  const effective = getEffectiveVersion(true);
+  const effectivePath = getBinaryPath(effective, true);
+
+  if (fs.existsSync(effectivePath) && isExecutable(effectivePath)) {
+    showWelcome();
+    maybeTriggerProUpdateCheck(licenseKey);
+    return effectivePath;
+  }
+
+  const version = await getProLatestVersion();
+  if (!version) {
+    throw new Error("Could not determine latest Pro version from server");
+  }
+
+  const versionPath = getBinaryPath(version, true);
+  if (fs.existsSync(versionPath) && isExecutable(versionPath)) {
+    showWelcome();
+    return versionPath;
+  }
+
+  console.log(
+    `[cloakbrowser] Downloading Pro Chromium ${version} for ${getPlatformTag()}...`
+  );
+  await downloadProBinary(version, licenseKey);
+
+  const downloadedPath = getBinaryPath(version, true);
+  if (!fs.existsSync(downloadedPath)) {
+    throw new Error(
+      `Pro download completed but binary not found at: ${downloadedPath}`
+    );
+  }
+
+  // Write Pro version marker
+  try {
+    const cacheDir = getCacheDir();
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const marker = path.join(cacheDir, `latest_pro_version_${getPlatformTag()}`);
+    fs.writeFileSync(marker, version);
+  } catch {
+    // Non-fatal
+  }
+
+  showWelcome();
+  return downloadedPath;
+}
+
+/** @internal Exported for testing only. */
+export async function downloadProBinary(version: string, licenseKey: string): Promise<void> {
+  // Request the explicit version so the served archive matches the signed
+  // manifest verified in verifyProDownload.
+  const downloadUrl = `${DOWNLOAD_BASE_URL}/api/download/${version}`;
+  const binaryDir = getBinaryDir(version, true);
+  const binaryPath = getBinaryPath(version, true);
+  const platformTag = getPlatformTag();
+
+  fs.mkdirSync(path.dirname(binaryDir), { recursive: true });
+
+  const tmpPath = path.join(
+    path.dirname(binaryDir),
+    `_download_${Date.now()}${getArchiveExt()}`
+  );
+
+  try {
+    await downloadFile(downloadUrl, tmpPath, {
+      Authorization: `Bearer ${licenseKey}`,
+      "X-Platform": platformTag,
+    });
+
+    // Pro binaries come from cloakbrowser.dev — the same origin as free
+    // downloads — so the M1 attack the Ed25519 signature defends against
+    // applies equally. Verify with the same non-bypassable signature check;
+    // CLOAKBROWSER_SKIP_CHECKSUM does NOT bypass it (parity with the official
+    // free path).
+    await verifyProDownload(tmpPath, version);
+
+    await extractArchive(tmpPath, binaryDir, binaryPath);
+  } finally {
+    if (fs.existsSync(tmpPath)) {
+      fs.unlinkSync(tmpPath);
+    }
+  }
+}
+
+/**
+ * Verify a Pro archive with the same non-bypassable Ed25519 signature check as
+ * official free downloads. Pro binaries are served from cloakbrowser.dev (same
+ * origin as the free tier), so a tampered same-origin SHA256SUMS could
+ * otherwise certify a tampered binary (M1, #308). Fetch the Pro SHA256SUMS +
+ * detached SHA256SUMS.sig, verify the signature against the pinned keys FIRST,
+ * bind the manifest to the requested version, then verify the archive's
+ * SHA-256.
+ *
+ * An invalid signature, checksum, or version mismatch throws
+ * BinaryVerificationError (a tampering signal the router surfaces verbatim);
+ * CLOAKBROWSER_SKIP_CHECKSUM cannot bypass it. A failed manifest FETCH is
+ * transient — nothing was validated — and throws a plain Error. A valid-license
+ * user is never silently downgraded to the free binary.
+ * @internal Exported for testing only.
+ */
+export async function verifyProDownload(filePath: string, version: string): Promise<void> {
+  const base = `${DOWNLOAD_BASE_URL}/releases/pro/chromium-v${version}`;
+  let manifestBytes: Uint8Array;
+  let sigBytes: Uint8Array;
+  try {
+    const manifestResp = await fetch(`${base}/SHA256SUMS`, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!manifestResp.ok) throw new Error(`HTTP ${manifestResp.status} for SHA256SUMS`);
+    const sigResp = await fetch(`${base}/SHA256SUMS.sig`, {
+      redirect: "follow",
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!sigResp.ok) throw new Error(`HTTP ${sigResp.status} for SHA256SUMS.sig`);
+    manifestBytes = new Uint8Array(await manifestResp.arrayBuffer());
+    sigBytes = new Uint8Array(await sigResp.arrayBuffer());
+  } catch (e) {
+    // Fetch failure is transient, not tampering — throw a plain Error (the
+    // router reports it as "unavailable, retry") rather than a
+    // BinaryVerificationError (which it surfaces as a tampering signal).
+    throw new Error(`Could not fetch the signed SHA256SUMS for Pro ${version} (${e})`);
+  }
+
+  // verifySignature / verifyChecksum throw a plain Error; convert to
+  // BinaryVerificationError so the Pro router treats them as tampering signals
+  // (re-throw) rather than transient failures (fall back to free).
+  try {
+    verifySignature(manifestBytes, sigBytes);
+  } catch (e) {
+    throw new BinaryVerificationError(e instanceof Error ? e.message : String(e));
+  }
+  const manifestText = new TextDecoder().decode(manifestBytes);
+
+  // Version binding: same forced-downgrade defense as the official path.
+  const declared = parseManifestVersion(manifestText);
+  if (declared !== version) {
+    throw new BinaryVerificationError(
+      `Version mismatch in signed Pro SHA256SUMS: requested ${version}, ` +
+        `manifest declares ${declared ?? "none"}. Refusing (possible downgrade).`
+    );
+  }
+
+  const tarballName = getArchiveName();
+  const expected = parseChecksums(manifestText).get(tarballName);
+  if (!expected) {
+    throw new BinaryVerificationError(
+      `Signature-verified Pro SHA256SUMS has no entry for ${tarballName} — ` +
+        `cannot confirm binary integrity.`
+    );
+  }
+  try {
+    await verifyChecksum(filePath, expected);
+  } catch (e) {
+    throw new BinaryVerificationError(e instanceof Error ? e.message : String(e));
+  }
+}
+
 async function extractArchive(
   archivePath: string,
   destDir: string,
@@ -615,3 +995,36 @@ function maybeTriggerUpdateCheck(): void {
   if (!shouldCheckForUpdate()) return;
   checkAndDownloadUpdate().catch(() => { });
 }
+
+function maybeTriggerProUpdateCheck(licenseKey: string): void {
+  const checkFile = path.join(getCacheDir(), ".last_pro_update_check");
+  try {
+    if (fs.existsSync(checkFile)) {
+      const lastCheck = parseFloat(fs.readFileSync(checkFile, "utf-8").trim());
+      if (Date.now() - lastCheck * 1000 < UPDATE_CHECK_INTERVAL_MS) return;
+    }
+  } catch {
+    // unreadable — proceed
+  }
+
+  (async () => {
+    try {
+      fs.mkdirSync(path.dirname(checkFile), { recursive: true });
+      fs.writeFileSync(checkFile, String(Date.now() / 1000));
+
+      const latest = await getProLatestVersion();
+      if (!latest) return;
+
+      if (fs.existsSync(getBinaryPath(latest, true))) return;
+
+      console.log(`[cloakbrowser] Newer Pro binary available: ${latest}. Downloading in background...`);
+      await downloadProBinary(latest, licenseKey);
+
+      const marker = path.join(getCacheDir(), `latest_pro_version_${getPlatformTag()}`);
+      fs.writeFileSync(marker, latest);
+      console.log(`[cloakbrowser] Pro background update complete: ${latest} ready. Will use on next launch.`);
+    } catch (err) {
+      // non-fatal
+    }
+  })();
+}

js/src/index.ts

@@ -24,5 +24,9 @@ export { ensureBinary, clearCache, binaryInfo, checkForUpdate } from "./download
 // Config
 export { CHROMIUM_VERSION, getDefaultStealthArgs } from "./config.js";
 
+// License
+export { validateLicense } from "./license.js";
+
 // Types
 export type { LaunchOptions, LaunchContextOptions, LaunchPersistentContextOptions, BinaryInfo } from "./types.js";
+export type { LicenseInfo } from "./license.js";

js/src/license.ts

@@ -0,0 +1,218 @@
+/**
+ * License validation and caching for CloakBrowser Pro.
+ * Mirrors Python cloakbrowser/license.py.
+ *
+ * Handles license key resolution, server validation with local caching,
+ * and Pro version checks.
+ */
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { getCacheDir } from "./config.js";
+
+const VALIDATE_URL = "https://cloakbrowser.dev/api/license/validate";
+const PRO_VERSION_URL = "https://cloakbrowser.dev/api/download/version";
+
+const LICENSE_CACHE_TTL_MS = 86_400_000; // 24 hours
+const PRO_VERSION_CHECK_INTERVAL_MS = 3_600_000; // 1 hour
+
+export interface LicenseInfo {
+  valid: boolean;
+  plan: string;
+  expires: string | null;
+}
+
+/**
+ * Resolve the license key: explicit param > env var > file > undefined.
+ */
+export function resolveLicenseKey(licenseKey?: string): string | undefined {
+  const trimmed = licenseKey?.trim();
+  if (trimmed) return trimmed;
+  const envKey = (process.env.CLOAKBROWSER_LICENSE_KEY ?? "").trim();
+  if (envKey) return envKey;
+  try {
+    const keyFile = path.join(getCacheDir(), "license.key");
+    const content = fs.readFileSync(keyFile, "utf-8").trim();
+    if (content) return content;
+  } catch {
+    // File doesn't exist or unreadable
+  }
+  return undefined;
+}
+
+/**
+ * Validate a license key with the CloakBrowser server.
+ *
+ * Checks a local file cache first (24h TTL). Falls back to stale
+ * cache if the server is unreachable.
+ *
+ * Returns LicenseInfo if validation succeeded, null on total failure.
+ */
+export async function validateLicense(licenseKey: string): Promise<LicenseInfo | null> {
+  const cachePath = path.join(getCacheDir(), ".license_cache");
+  const keySha = createHash("sha256").update(licenseKey).digest("hex");
+
+  const cached = readCache(cachePath, keySha);
+  if (cached) return cached;
+
+  try {
+    const resp = await fetch(VALIDATE_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ license_key: licenseKey }),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!resp.ok) {
+      throw new Error(`HTTP ${resp.status} ${resp.statusText}`);
+    }
+
+    const data = (await resp.json()) as Record<string, unknown>;
+
+    const info: LicenseInfo = {
+      valid: Boolean(data.valid ?? false),
+      plan: String(data.plan ?? "solo"),
+      expires: data.expires != null ? String(data.expires) : null,
+    };
+
+    if (info.valid) {
+      writeCache(cachePath, keySha, info);
+    }
+    return info;
+  } catch (e) {
+    console.warn(
+      `[cloakbrowser] License validation request failed: ${e instanceof Error ? e.message : e}`
+    );
+
+    // Fall back to stale cache
+    const stale = readCache(cachePath, keySha, true);
+    if (stale) {
+      console.warn("[cloakbrowser] Using cached license validation (server unreachable)");
+      return stale;
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Get the latest Pro binary version from the server.
+ * Rate-limited to 1 call per hour via a marker file.
+ */
+export async function getProLatestVersion(): Promise<string | null> {
+  const marker = path.join(getCacheDir(), ".last_pro_version_check");
+
+  try {
+    if (fs.existsSync(marker)) {
+      const stats = fs.statSync(marker);
+      const age = Date.now() - stats.mtimeMs;
+      if (age < PRO_VERSION_CHECK_INTERVAL_MS) {
+        const content = fs.readFileSync(marker, "utf-8").trim();
+        return content || null;
+      }
+    }
+  } catch {
+    // Marker unreadable — proceed with fetch
+  }
+
+  try {
+    const resp = await fetch(PRO_VERSION_URL, {
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!resp.ok) {
+      throw new Error(`HTTP ${resp.status} ${resp.statusText}`);
+    }
+
+    const data = (await resp.json()) as Record<string, unknown>;
+    const version = data.version != null ? String(data.version) : null;
+    if (!version) return null;
+
+    try {
+      fs.mkdirSync(path.dirname(marker), { recursive: true });
+      fs.writeFileSync(marker, version);
+    } catch {
+      // Non-fatal
+    }
+
+    return version;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cache helpers
+// ---------------------------------------------------------------------------
+
+interface CacheData {
+  key_sha256: string;
+  valid: boolean;
+  plan: string;
+  expires: string | null;
+  validated_at: number;
+}
+
+function readCache(
+  cachePath: string,
+  keySha: string,
+  ignoreTtl = false,
+): LicenseInfo | null {
+  try {
+    if (!fs.existsSync(cachePath)) return null;
+
+    const data = JSON.parse(fs.readFileSync(cachePath, "utf-8")) as CacheData;
+
+    if (data.key_sha256 !== keySha) return null;
+
+    if (!ignoreTtl) {
+      const validatedAt = data.validated_at ?? 0;
+      // A non-numeric validated_at (corrupted cache) is treated as absent rather
+      // than coercing to NaN and silently trusting the entry.
+      if (!Number.isFinite(validatedAt) || Date.now() - validatedAt * 1000 > LICENSE_CACHE_TTL_MS) {
+        return null;
+      }
+    }
+
+    if (data.expires) {
+      try {
+        if (new Date(data.expires).getTime() < Date.now()) {
+          return { valid: false, plan: String(data.plan ?? "solo"), expires: data.expires };
+        }
+      } catch {
+        // unparseable date — skip check
+      }
+    }
+
+    return {
+      valid: Boolean(data.valid ?? false),
+      plan: String(data.plan ?? "solo"),
+      expires: data.expires ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cachePath: string, keySha: string, info: LicenseInfo): void {
+  try {
+    const dir = path.dirname(cachePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmpPath = cachePath + ".tmp";
+    fs.writeFileSync(
+      tmpPath,
+      JSON.stringify({
+        key_sha256: keySha,
+        valid: info.valid,
+        plan: info.plan,
+        expires: info.expires,
+        validated_at: Date.now() / 1000,
+      }),
+    );
+    fs.renameSync(tmpPath, cachePath);
+  } catch {
+    // Non-fatal
+  }
+}

js/src/playwright.ts

@@ -52,15 +52,43 @@ function filterStealthCtxOptions(ctx?: BrowserContextOptions): Partial<BrowserCo
  * Useful when integrating CloakBrowser with an existing Playwright Browser while
  * keeping the wrapper's stealth-safe defaults for `newContext()`.
  */
+/**
+ * Effective headless mode for viewport decisions. buildLaunchOptions() spreads
+ * `...options.launchOptions` LAST, so a raw `launchOptions.headless` overrides the
+ * top-level field at the actual chromium.launch() call. Viewport logic must read
+ * the same effective value — otherwise a headed browser gets a fixed viewport
+ * (reintroducing the impossible-window tell). Playwright-specific (Puppeteer
+ * resolves headless the opposite way).
+ */
+function effectiveHeadless(options: LaunchOptions): boolean {
+  return (
+    (options.launchOptions as { headless?: boolean } | undefined)?.headless ??
+    options.headless ??
+    true
+  );
+}
+
 export function buildContextOptions(
   options: LaunchContextOptions = {}
 ): BrowserContextOptions {
+  // Headed: viewport=null (no emulation) so the page tracks the real window and
+  // outerWidth >= innerWidth stays coherent — CDP viewport emulation forces
+  // inner > outer = a physically impossible window = bot tell. Headless has no
+  // window chrome (outer == inner), so a fixed viewport stays coherent and keeps
+  // dimensions deterministic. Explicit viewport (incl. null) is always honored.
+  const headless = effectiveHeadless(options);
+  const viewport =
+    options.viewport !== undefined
+      ? options.viewport
+      : headless
+        ? DEFAULT_VIEWPORT
+        : null;
   return {
     // contextOptions first — explicit wrapper fields below override it.
     // filterStealthCtxOptions strips locale/timezoneId to prevent CDP detection.
     ...filterStealthCtxOptions(options.contextOptions),
     ...(options.userAgent ? { userAgent: options.userAgent } : {}),
-    viewport: options.viewport === undefined ? DEFAULT_VIEWPORT : options.viewport,
+    viewport,
     ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),
   } as BrowserContextOptions;
 }
@@ -74,7 +102,7 @@ export function buildContextOptions(
 export async function buildLaunchOptions(
   options: LaunchOptions = {}
 ): Promise<PlaywrightLaunchOptions> {
-  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
+  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary(options.licenseKey));
   const { exitIp, ...resolved } = await maybeResolveGeoip(options);
   const { proxyOption, proxyArgs } = resolveProxyConfig(options.proxy);
   let resolvedArgs = await resolveWebrtcArgs(options);
@@ -127,10 +155,33 @@ export async function humanizeBrowser(
 export async function launch(options: LaunchOptions = {}): Promise<Browser> {
   const { chromium } = await import("playwright-core");
   const browser = await chromium.launch(await buildLaunchOptions(options));
+  // Headed: a bare browser.newPage() would inherit Playwright's emulated 1280x720
+  // viewport -> outerWidth < innerWidth (impossible window = bot tell). Default
+  // newPage()/newContext() to viewport:null so the page tracks the real window.
+  // Headless keeps Playwright's default viewport (coherent there).
+  if (!effectiveHeadless(options)) {
+    applyDefaultNoViewport(browser);
+  }
   await humanizeBrowser(browser, options);
   return browser;
 }
 
+/**
+ * Wrap a Browser's newContext()/newPage() to default to viewport:null (no
+ * emulation) when the caller didn't specify a viewport. setdefault-style: an
+ * explicit viewport (including null) is always honored. Apply before humanize's
+ * patchBrowser so the wraps compose.
+ */
+function applyDefaultNoViewport(browser: Browser): void {
+  const origNewContext = browser.newContext.bind(browser);
+  (browser as any).newContext = (options?: Parameters<typeof origNewContext>[0]) =>
+    origNewContext(options?.viewport === undefined ? { ...options, viewport: null } : options);
+
+  const origNewPage = browser.newPage.bind(browser);
+  (browser as any).newPage = (options?: Parameters<typeof origNewPage>[0]) =>
+    origNewPage(options?.viewport === undefined ? { ...options, viewport: null } : options);
+}
+
 /**
  * Launch stealth browser and return a BrowserContext with common options pre-set.
  * Closing the context also closes the browser.
@@ -161,7 +212,9 @@ export async function launchContext(
   // --fingerprint-timezone is process-wide (reads CommandLine in renderer),
   // so it applies to ALL contexts, not just the default one.
   // locale and timezone are set via binary flags only — no CDP emulation.
-  const browser = await launch({ ...options, ...resolved, args: launchArgs, geoip: false });
+  // humanize:false on the inner launch — patchContext below applies humanize
+  // exactly once (else launch()'s humanizeBrowser would patch it a second time).
+  const browser = await launch({ ...options, ...resolved, args: launchArgs, geoip: false, humanize: false });
 
   let context: BrowserContext;
   try {
@@ -219,7 +272,7 @@ export async function launchPersistentContext(
   options = resolveTimezone(options);
   const { chromium } = await import("playwright-core");
 
-  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
+  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary(options.licenseKey));
   const { exitIp, ...resolved } = await maybeResolveGeoip(options);
   const { proxyOption, proxyArgs } = resolveProxyConfig(options.proxy);
   let resolvedArgs = await resolveWebrtcArgs(options);

js/src/puppeteer.ts

@@ -6,16 +6,34 @@
 
 import type { Browser } from "puppeteer-core";
 import type { LaunchOptions } from "./types.js";
-import { IGNORE_DEFAULT_ARGS } from "./config.js";
+import { DEFAULT_VIEWPORT, IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
 import { isSocksProxy, normalizeHttpStringUrl, parseProxyUrl, reconstructHttpUrl, resolveProxyConfig, supportsHttpProxyInlineAuth } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
 import { seedWidevineHint } from "./widevine.js";
 
+/**
+ * Resolve Puppeteer's defaultViewport. Headed -> null (track the real window so
+ * outerWidth >= innerWidth stays coherent; Puppeteer otherwise forces an 800x600
+ * emulated viewport = a physically impossible window = bot tell). Headless has no
+ * window chrome (outer == inner), so a fixed viewport stays coherent and keeps
+ * dimensions deterministic. A user-supplied launchOptions.defaultViewport wins.
+ */
+function resolveDefaultViewport(options: LaunchOptions): { width: number; height: number } | null {
+  const launchOpts = (options.launchOptions ?? {}) as Record<string, unknown>;
+  // A user-supplied defaultViewport wins (incl. explicit null). undefined is NOT
+  // "supplied" — fall through to our default. Puppeteer sets `headless` AFTER the
+  // launchOptions spread, so the top-level field wins at launch — match it here.
+  if (launchOpts.defaultViewport !== undefined) {
+    return launchOpts.defaultViewport as { width: number; height: number } | null;
+  }
+  return (options.headless ?? true) ? DEFAULT_VIEWPORT : null;
+}
+
 /** Resolve binary path, geoip, webrtc, and build final Chrome args. */
 async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string; args: string[] }> {
-  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
+  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary(options.licenseKey));
   const { exitIp, ...resolved } = (await maybeResolveGeoip(options)) ?? {};
   let resolvedArgs = (await resolveWebrtcArgs(options)) ?? options.args;
 
@@ -125,6 +143,7 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
     headless: options.headless ?? true,
     args,
     ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+    defaultViewport: resolveDefaultViewport(options),
   });
 
   await applyPostLaunch(browser, options, proxyAuth);
@@ -165,6 +184,7 @@ export async function launchPersistentContext(
     args,
     ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
     userDataDir: options.userDataDir,
+    defaultViewport: resolveDefaultViewport(options),
   });
 
   await applyPostLaunch(browser, options, proxyAuth);

js/src/types.ts

@@ -27,6 +27,8 @@ export interface LaunchOptions {
   locale?: string;
   /** Auto-detect timezone/locale from proxy IP (requires: npm install mmdb-lib). */
   geoip?: boolean;
+  /** Pro license key. Also reads from CLOAKBROWSER_LICENSE_KEY env var. */
+  licenseKey?: string;
   /** Raw options passed directly to playwright/puppeteer launch(). */
   launchOptions?: Record<string, unknown>;
   /** Enable human-like mouse, keyboard, and scroll behavior. */
@@ -66,7 +68,10 @@ export interface LaunchPersistentContextOptions extends LaunchContextOptions {
 
 export interface BinaryInfo {
   version: string;
+  /** The wrapper's bundled baseline Chromium version (CHROMIUM_VERSION). */
+  bundledVersion: string;
   platform: string;
+  tier: "pro" | "free";
   binaryPath: string;
   installed: boolean;
   cacheDir: string;

js/tests/launch.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
 import { binaryInfo } from "../src/download.js";
-import { DEFAULT_VIEWPORT, getChromiumVersion } from "../src/config.js";
+import { DEFAULT_VIEWPORT, getBinaryPath, getChromiumVersion, getPlatformTag } from "../src/config.js";
 import * as config from "../src/config.js";
 
 describe("binaryInfo", () => {
@@ -11,6 +13,7 @@ describe("binaryInfo", () => {
       const info = binaryInfo();
 
       expect(info.version).toBe(getChromiumVersion());
+      expect(info.bundledVersion).toBeTruthy();
       expect(info.platform).toMatch(/^(linux|darwin|windows)-(x64|arm64)$/);
       expect(info.binaryPath).toBeTruthy();
       expect(typeof info.installed).toBe("boolean");
@@ -20,6 +23,41 @@ describe("binaryInfo", () => {
       else delete process.env.CLOAKBROWSER_CACHE_DIR;
     }
   });
+
+  it("reports tier from the installed binary, not a cached license", () => {
+    // A valid, fresh license is cached but NO Pro binary is on disk → free.
+    const orig = process.env.CLOAKBROWSER_CACHE_DIR;
+    const dir = `/tmp/cloakbrowser-test-${Date.now()}-tier`;
+    fs.mkdirSync(dir, { recursive: true });
+    process.env.CLOAKBROWSER_CACHE_DIR = dir;
+    try {
+      fs.writeFileSync(
+        path.join(dir, ".license_cache"),
+        JSON.stringify({
+          key_sha256: "abc",
+          valid: true,
+          plan: "solo",
+          expires: null,
+          validated_at: Date.now() / 1000,
+        })
+      );
+      expect(binaryInfo().tier).toBe("free");
+
+      // Now drop a Pro binary on disk → pro.
+      fs.writeFileSync(path.join(dir, `latest_pro_version_${getPlatformTag()}`), "147.0.5555.1");
+      const bp = getBinaryPath("147.0.5555.1", true);
+      fs.mkdirSync(path.dirname(bp), { recursive: true });
+      fs.writeFileSync(bp, "fake");
+      fs.chmodSync(bp, 0o755);
+      const info = binaryInfo();
+      expect(info.tier).toBe("pro");
+      expect(info.version).toBe("147.0.5555.1");
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+      if (orig) process.env.CLOAKBROWSER_CACHE_DIR = orig;
+      else delete process.env.CLOAKBROWSER_CACHE_DIR;
+    }
+  });
 });
 
 describe("composable Playwright launch helpers", () => {
@@ -84,6 +122,32 @@ describe("composable Playwright launch helpers", () => {
     expect(buildContextOptions({ viewport: null }).viewport).toBeNull();
   });
 
+  it("buildContextOptions uses no viewport (null) when headed, so the page tracks the real window", async () => {
+    const { buildContextOptions } = await import("../src/index.js");
+
+    // Headed: no emulated viewport (CDP emulation would force outerWidth < innerWidth).
+    expect(buildContextOptions({ headless: false }).viewport).toBeNull();
+    // Headless keeps the deterministic default.
+    expect(buildContextOptions({ headless: true }).viewport).toEqual(DEFAULT_VIEWPORT);
+    // Explicit viewport always honored, even headed.
+    const custom = { width: 800, height: 600 };
+    expect(buildContextOptions({ headless: false, viewport: custom }).viewport).toEqual(custom);
+  });
+
+  it("buildContextOptions reads effective headless from launchOptions.headless", async () => {
+    const { buildContextOptions } = await import("../src/index.js");
+
+    // buildLaunchOptions spreads launchOptions LAST, so launchOptions.headless wins
+    // at the actual launch. Viewport must follow it — a raw headless:false (browser
+    // actually headed) must NOT get a fixed viewport (would reintroduce outer<inner).
+    expect(buildContextOptions({ launchOptions: { headless: false } }).viewport).toBeNull();
+    // And launchOptions.headless:true forces the deterministic viewport even if the
+    // top-level field said headed.
+    expect(
+      buildContextOptions({ headless: false, launchOptions: { headless: true } }).viewport,
+    ).toEqual(DEFAULT_VIEWPORT);
+  });
+
   it("buildLaunchOptions returns Playwright options without launching a browser", async () => {
     const freshConfig = await import("../src/config.js");
     vi.spyOn(freshConfig, "getPlatformTag").mockReturnValue("darwin-arm64");

js/tests/license.test.ts

@@ -0,0 +1,312 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+
+import {
+  resolveLicenseKey,
+  validateLicense,
+  getProLatestVersion,
+} from "../src/license.js";
+
+import * as config from "../src/config.js";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = path.join("/tmp", `cloakbrowser-test-${Date.now()}`);
+  fs.mkdirSync(tmpDir, { recursive: true });
+  vi.spyOn(config, "getCacheDir").mockReturnValue(tmpDir);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  try {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {}
+});
+
+// ── resolveLicenseKey ─────────────────────────────────
+
+describe("resolveLicenseKey", () => {
+  it("explicit param wins over env", () => {
+    process.env.CLOAKBROWSER_LICENSE_KEY = "env-key";
+    expect(resolveLicenseKey("explicit")).toBe("explicit");
+    delete process.env.CLOAKBROWSER_LICENSE_KEY;
+  });
+
+  it("env var fallback", () => {
+    process.env.CLOAKBROWSER_LICENSE_KEY = "env-key";
+    expect(resolveLicenseKey()).toBe("env-key");
+    delete process.env.CLOAKBROWSER_LICENSE_KEY;
+  });
+
+  it("returns undefined when absent", () => {
+    delete process.env.CLOAKBROWSER_LICENSE_KEY;
+    expect(resolveLicenseKey()).toBeUndefined();
+  });
+
+  it("file fallback when no param or env", () => {
+    delete process.env.CLOAKBROWSER_LICENSE_KEY;
+    const keyFile = path.join(tmpDir, "license.key");
+    fs.writeFileSync(keyFile, "file-key-123\n");
+    expect(resolveLicenseKey()).toBe("file-key-123");
+  });
+
+  it("env takes precedence over file", () => {
+    process.env.CLOAKBROWSER_LICENSE_KEY = "env-key";
+    const keyFile = path.join(tmpDir, "license.key");
+    fs.writeFileSync(keyFile, "file-key");
+    expect(resolveLicenseKey()).toBe("env-key");
+    delete process.env.CLOAKBROWSER_LICENSE_KEY;
+  });
+
+  it("returns undefined when file missing", () => {
+    delete process.env.CLOAKBROWSER_LICENSE_KEY;
+    expect(resolveLicenseKey()).toBeUndefined();
+  });
+});
+
+// ── validateLicense ───────────────────────────────────
+
+describe("validateLicense", () => {
+  const keySha = crypto.createHash("sha256").update("test-key").digest("hex");
+
+  it("fresh cache skips server call", async () => {
+    const cachePath = path.join(tmpDir, ".license_cache");
+    fs.writeFileSync(
+      cachePath,
+      JSON.stringify({
+        key_sha256: keySha,
+        valid: true,
+        plan: "team",
+        expires: "2026-12-01",
+        validated_at: Date.now() / 1000,
+      })
+    );
+
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    const result = await validateLicense("test-key");
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(result).not.toBeNull();
+    expect(result!.valid).toBe(true);
+    expect(result!.plan).toBe("team");
+  });
+
+  it("stale cache triggers server call", async () => {
+    const cachePath = path.join(tmpDir, ".license_cache");
+    fs.writeFileSync(
+      cachePath,
+      JSON.stringify({
+        key_sha256: keySha,
+        valid: true,
+        plan: "solo",
+        expires: null,
+        validated_at: Date.now() / 1000 - 90000, // 25 hours ago
+      })
+    );
+
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true, plan: "solo", expires: null }),
+    } as Response);
+
+    const result = await validateLicense("test-key");
+    expect(globalThis.fetch).toHaveBeenCalledOnce();
+    expect(result!.valid).toBe(true);
+  });
+
+  it("server success returns LicenseInfo", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true, plan: "business", expires: "2026-07-13" }),
+    } as Response);
+
+    const result = await validateLicense("pro-key");
+    expect(result).not.toBeNull();
+    expect(result!.valid).toBe(true);
+    expect(result!.plan).toBe("business");
+    expect(result!.expires).toBe("2026-07-13");
+  });
+
+  it("server rejection returns invalid", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: false, plan: "solo", expires: null }),
+    } as Response);
+
+    const result = await validateLicense("bad-key");
+    expect(result).not.toBeNull();
+    expect(result!.valid).toBe(false);
+  });
+
+  it("server unreachable uses stale cache", async () => {
+    const cachePath = path.join(tmpDir, ".license_cache");
+    fs.writeFileSync(
+      cachePath,
+      JSON.stringify({
+        key_sha256: keySha,
+        valid: true,
+        plan: "solo",
+        expires: "2026-12-01",
+        validated_at: Date.now() / 1000 - 90000,
+      })
+    );
+
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("timeout"));
+
+    const result = await validateLicense("test-key");
+    expect(result).not.toBeNull();
+    expect(result!.valid).toBe(true);
+  });
+
+  it("server unreachable no cache returns null", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("timeout"));
+
+    const result = await validateLicense("test-key");
+    expect(result).toBeNull();
+  });
+
+  it("cache stores hash not raw key", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true, plan: "solo", expires: null }),
+    } as Response);
+
+    await validateLicense("secret-key-123");
+
+    const cachePath = path.join(tmpDir, ".license_cache");
+    const content = fs.readFileSync(cachePath, "utf-8");
+    expect(content).not.toContain("secret-key-123");
+    const expectedSha = crypto
+      .createHash("sha256")
+      .update("secret-key-123")
+      .digest("hex");
+    expect(content).toContain(expectedSha);
+  });
+
+  it("wrong key cache ignored", async () => {
+    const cachePath = path.join(tmpDir, ".license_cache");
+    fs.writeFileSync(
+      cachePath,
+      JSON.stringify({
+        key_sha256: "other-hash",
+        valid: true,
+        plan: "solo",
+        expires: null,
+        validated_at: Date.now() / 1000,
+      })
+    );
+
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true, plan: "solo", expires: null }),
+    } as Response);
+
+    await validateLicense("different-key");
+    expect(globalThis.fetch).toHaveBeenCalledOnce();
+  });
+
+  it("expired license rejected from cache", async () => {
+    const cachePath = path.join(tmpDir, ".license_cache");
+    const keySha = crypto.createHash("sha256").update("test-key").digest("hex");
+    fs.writeFileSync(
+      cachePath,
+      JSON.stringify({
+        key_sha256: keySha,
+        valid: true,
+        plan: "solo",
+        expires: "2020-01-01T00:00:00+00:00",
+        validated_at: Date.now() / 1000,
+      })
+    );
+
+    const result = await validateLicense("test-key");
+    expect(result).not.toBeNull();
+    expect(result!.valid).toBe(false);
+  });
+
+  it("does not cache invalid responses", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: false, plan: "solo", expires: null }),
+    } as Response);
+
+    await validateLicense("bad-key");
+
+    const cachePath = path.join(tmpDir, ".license_cache");
+    expect(fs.existsSync(cachePath)).toBe(false);
+  });
+
+  it("corrupted validated_at is treated as absent cache, not trusted", async () => {
+    const keySha = crypto.createHash("sha256").update("test-key").digest("hex");
+    fs.writeFileSync(
+      path.join(tmpDir, ".license_cache"),
+      JSON.stringify({
+        key_sha256: keySha,
+        valid: true,
+        plan: "solo",
+        expires: null,
+        validated_at: "not-a-number",
+      })
+    );
+
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ valid: true, plan: "solo", expires: null }),
+    } as Response);
+
+    const result = await validateLicense("test-key");
+    expect(globalThis.fetch).toHaveBeenCalledOnce(); // corrupted cache ignored → server hit
+    expect(result!.valid).toBe(true);
+  });
+});
+
+// ── getProLatestVersion ───────────────────────────────
+
+describe("getProLatestVersion", () => {
+  it("fetches version from server", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "147.0.1234.5" }),
+    } as Response);
+
+    const version = await getProLatestVersion();
+    expect(version).toBe("147.0.1234.5");
+  });
+
+  it("rate limited by marker file", async () => {
+    const marker = path.join(tmpDir, ".last_pro_version_check");
+    fs.writeFileSync(marker, "147.0.1234.5");
+
+    const fetchSpy = vi.spyOn(globalThis, "fetch");
+    const version = await getProLatestVersion();
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(version).toBe("147.0.1234.5");
+  });
+
+  it("network error returns null", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("network"));
+    const version = await getProLatestVersion();
+    expect(version).toBeNull();
+  });
+});
+
+// ── Config pro parameter ──────────────────────────────
+
+describe("config pro parameter", () => {
+  it("getBinaryDir adds -pro suffix", () => {
+    const normal = config.getBinaryDir("147.0.0.0");
+    const pro = config.getBinaryDir("147.0.0.0", true);
+    expect(normal).toMatch(/chromium-147\.0\.0\.0$/);
+    expect(pro).toMatch(/chromium-147\.0\.0\.0-pro$/);
+  });
+
+  it("getBinaryDir default has no suffix", () => {
+    const normal = config.getBinaryDir("147.0.0.0");
+    expect(normal).not.toMatch(/-pro$/);
+  });
+});

js/tests/puppeteer.test.ts

@@ -65,6 +65,53 @@ describe("puppeteer launch", () => {
     expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(false);
   });
 
+  it("headless (default) uses a fixed defaultViewport; headed uses null", async () => {
+    const { DEFAULT_VIEWPORT } = await import("../src/config.js");
+    const { launch } = await import("../src/puppeteer.js");
+
+    // Headless (default): deterministic viewport.
+    await launch();
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toEqual(DEFAULT_VIEWPORT);
+
+    // Headed: null so the page tracks the real window (else Puppeteer forces 800x600).
+    vi.mocked(puppeteerMock.default.launch).mockClear();
+    await launch({ headless: false });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toBeNull();
+  });
+
+  it("honors an explicit launchOptions.defaultViewport (incl. null)", async () => {
+    const { launch } = await import("../src/puppeteer.js");
+
+    const custom = { width: 640, height: 480 };
+    await launch({ headless: true, launchOptions: { defaultViewport: custom } });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toEqual(custom);
+
+    // Explicit null honored even in headless (would otherwise default to DEFAULT_VIEWPORT).
+    vi.mocked(puppeteerMock.default.launch).mockClear();
+    await launch({ headless: true, launchOptions: { defaultViewport: null } });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toBeNull();
+  });
+
+  it("Puppeteer headless precedence: top-level headless wins over launchOptions.headless", async () => {
+    const { DEFAULT_VIEWPORT } = await import("../src/config.js");
+    const { launch } = await import("../src/puppeteer.js");
+
+    // Puppeteer sets headless AFTER the launchOptions spread, so top-level wins at
+    // launch — the viewport decision must follow the same (top-level) value.
+    await launch({ headless: true, launchOptions: { headless: false } });
+    const opts = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(opts.headless).toBe(true);
+    expect(opts.defaultViewport).toEqual(DEFAULT_VIEWPORT);
+  });
+
   it("adds --proxy-server for string proxy", async () => {
     const { launch } = await import("../src/puppeteer.js");
     await launch({ proxy: "http://proxy:8080" });
@@ -212,6 +259,22 @@ describe("puppeteer launchPersistentContext", () => {
     expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(true);
   });
 
+  it("headed persistent context uses null defaultViewport (tracks real window)", async () => {
+    const { DEFAULT_VIEWPORT } = await import("../src/config.js");
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+
+    await launchPersistentContext({ userDataDir: "./my-profile", headless: false });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toBeNull();
+
+    vi.mocked(puppeteerMock.default.launch).mockClear();
+    await launchPersistentContext({ userDataDir: "./my-profile", headless: true });
+    expect(
+      vi.mocked(puppeteerMock.default.launch).mock.calls[0][0].defaultViewport
+    ).toEqual(DEFAULT_VIEWPORT);
+  });
+
   it("uses page.authenticate fallback for http proxy in persistent context on unsupported platform", async () => {
     const config = await import("../src/config.js");
     vi.spyOn(config, "getPlatformTag").mockReturnValue("darwin-arm64");

js/tests/signature.test.ts

@@ -0,0 +1,336 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { sign as cryptoSign, createPrivateKey, createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Generate a throwaway signing keypair BEFORE the config mock is hoisted, then
+// pin its public key so verifySignature accepts signatures we produce here.
+const h = vi.hoisted(() => {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const crypto = require("node:crypto");
+  const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+  const otherPub = crypto.generateKeyPairSync("ed25519").publicKey;
+  const rawB64 = (pk: any) =>
+    Buffer.from(pk.export({ format: "jwk" }).x, "base64url").toString("base64");
+  return {
+    pinnedPubB64: rawB64(publicKey),
+    otherPubB64: rawB64(otherPub),
+    privPem: privateKey.export({ type: "pkcs8", format: "pem" }) as string,
+  };
+});
+
+vi.mock("../src/config.js", async (importActual) => {
+  const actual = await importActual<typeof import("../src/config.js")>();
+  return { ...actual, BINARY_SIGNING_PUBKEYS: [h.pinnedPubB64] };
+});
+
+import {
+  BinaryVerificationError,
+  downloadProBinary,
+  fetchSignedManifest,
+  parseChecksums,
+  parseManifestVersion,
+  verifyDownloadChecksum,
+  verifyProDownload,
+  verifySignature,
+} from "../src/download.js";
+import { DOWNLOAD_BASE_URL, getArchiveName, getChromiumVersion } from "../src/config.js";
+
+/** Produce SHA256SUMS.sig content (base64 text bytes) for a manifest. */
+function sign(manifest: Uint8Array): Uint8Array {
+  const priv = createPrivateKey(h.privPem);
+  const sig = cryptoSign(null, manifest, priv); // raw 64-byte Ed25519 signature
+  return new TextEncoder().encode(sig.toString("base64"));
+}
+
+const enc = (s: string) => new TextEncoder().encode(s);
+
+describe("verifySignature", () => {
+  it("accepts a valid signature", () => {
+    const manifest = enc("abc  cloakbrowser-linux-x64.tar.gz\n");
+    expect(() => verifySignature(manifest, sign(manifest))).not.toThrow();
+  });
+
+  it("rejects a tampered manifest", () => {
+    const manifest = enc("abc  cloakbrowser-linux-x64.tar.gz\n");
+    const sig = sign(manifest);
+    const tampered = enc("xyz  cloakbrowser-linux-x64.tar.gz\n");
+    expect(() => verifySignature(tampered, sig)).toThrow(/signature verification failed/);
+  });
+
+  it("rejects malformed base64 in the .sig", () => {
+    expect(() => verifySignature(enc("data\n"), enc("!!!not base64!!!")))
+      .toThrow(/Malformed/);
+  });
+
+  it("rejects a signature from a non-pinned key", async () => {
+    // Re-mock config so ONLY the other key is pinned, then the signature
+    // (made with the real key) must fail.
+    vi.resetModules();
+    vi.doMock("../src/config.js", async (importActual) => {
+      const actual = await importActual<typeof import("../src/config.js")>();
+      return { ...actual, BINARY_SIGNING_PUBKEYS: [h.otherPubB64] };
+    });
+    const { verifySignature: vs } = await import("../src/download.js");
+    const manifest = enc("data\n");
+    expect(() => vs(manifest, sign(manifest))).toThrow(/signature verification failed/);
+    vi.doUnmock("../src/config.js");
+    vi.resetModules();
+  });
+
+  it("accepts a signature under the new key during rotation", async () => {
+    // Pin BOTH keys (old + new) and sign with the real (new) key — must pass.
+    vi.resetModules();
+    vi.doMock("../src/config.js", async (importActual) => {
+      const actual = await importActual<typeof import("../src/config.js")>();
+      return { ...actual, BINARY_SIGNING_PUBKEYS: [h.otherPubB64, h.pinnedPubB64] };
+    });
+    const { verifySignature: vs } = await import("../src/download.js");
+    const manifest = enc("rotated\n");
+    expect(() => vs(manifest, sign(manifest))).not.toThrow();
+    vi.doUnmock("../src/config.js");
+    vi.resetModules();
+  });
+});
+
+describe("verifyDownloadChecksum (official path, fail-closed)", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.CLOAKBROWSER_DOWNLOAD_URL;
+    delete process.env.CLOAKBROWSER_SKIP_CHECKSUM;
+  });
+
+  function tmpFile(bytes: Buffer): string {
+    const p = path.join(os.tmpdir(), `cloak-sig-${process.pid}-${bytes.length}-${bytes[0]}`);
+    fs.writeFileSync(p, bytes);
+    return p;
+  }
+
+  /** Mock fetch to serve a signed manifest for the official URLs. */
+  function mockManifest(manifestBytes: Uint8Array) {
+    const sig = sign(manifestBytes);
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = typeof input === "string" ? input : (input as URL).toString();
+      const body = url.endsWith(".sig") ? sig : manifestBytes;
+      return { ok: true, arrayBuffer: async () => body.buffer } as Response;
+    });
+  }
+
+  /** Manifest body with the bound version line prepended (defaults to current). */
+  const body = (lines: string, version = getChromiumVersion()) =>
+    enc(`version=${version}\n${lines}`);
+
+  it("passes when signature is valid and hash matches", async () => {
+    const data = Buffer.from("the real binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    mockManifest(body(`${hash}  ${getArchiveName()}\n`));
+    await expect(verifyDownloadChecksum(file)).resolves.toBeUndefined();
+  });
+
+  it("fails when the binary is tampered (hash mismatch)", async () => {
+    const file = tmpFile(Buffer.from("a malicious binary"));
+    const goodHash = createHash("sha256").update(Buffer.from("the real binary")).digest("hex");
+    mockManifest(body(`${goodHash}  ${getArchiveName()}\n`));
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/Checksum verification failed/);
+  });
+
+  it("fails on a signed manifest for the wrong version (downgrade)", async () => {
+    const data = Buffer.from("the real binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    // Genuinely signed, but declares an old version we did not request.
+    mockManifest(body(`${hash}  ${getArchiveName()}\n`, "1.0.0.0"));
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/Version mismatch/);
+  });
+
+  it("fails when the version line is missing (binding required)", async () => {
+    const data = Buffer.from("the real binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    mockManifest(enc(`${hash}  ${getArchiveName()}\n`)); // no version= line
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/Version mismatch/);
+  });
+
+  it("fails closed when no signed manifest can be fetched", async () => {
+    const file = tmpFile(Buffer.from("x"));
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({ ok: false, status: 404 } as Response);
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/signed SHA256SUMS/);
+  });
+
+  it("fails when the signed manifest has no entry for this platform", async () => {
+    const file = tmpFile(Buffer.from("x"));
+    const someHash = "0".repeat(64);
+    mockManifest(body(`${someHash}  some-other-file.tar.gz\n`));
+    await expect(verifyDownloadChecksum(file)).rejects.toThrow(/no entry for/);
+  });
+
+  it("custom download URL keeps the legacy skippable path (no signature fetch)", async () => {
+    const file = tmpFile(Buffer.from("x"));
+    process.env.CLOAKBROWSER_DOWNLOAD_URL = "https://my-mirror.test";
+    process.env.CLOAKBROWSER_SKIP_CHECKSUM = "true";
+    const spy = vi.spyOn(globalThis, "fetch");
+    await expect(verifyDownloadChecksum(file)).resolves.toBeUndefined();
+    expect(spy).not.toHaveBeenCalled();
+  });
+});
+
+describe("downloadProBinary (version-pinned URL)", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("requests the explicit version, not /latest", async () => {
+    let capturedUrl = "";
+    // First fetch is the binary download; capture its URL then abort the flow
+    // before verify/extract by returning a non-ok response.
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      capturedUrl = typeof input === "string" ? input : (input as URL).toString();
+      return { ok: false, status: 500, statusText: "stop" } as Response;
+    });
+
+    await downloadProBinary("147.0.1.0", "cb_key").catch(() => {});
+
+    expect(capturedUrl).toBe(`${DOWNLOAD_BASE_URL}/api/download/147.0.1.0`);
+    expect(capturedUrl.endsWith("/latest")).toBe(false);
+  });
+});
+
+describe("verifyProDownload (Pro path, fail-closed parity)", () => {
+  const PRO_VERSION = "147.0.1.0";
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.CLOAKBROWSER_SKIP_CHECKSUM;
+  });
+
+  function tmpFile(bytes: Buffer): string {
+    const p = path.join(os.tmpdir(), `cloak-pro-${process.pid}-${bytes.length}-${bytes[0]}`);
+    fs.writeFileSync(p, bytes);
+    return p;
+  }
+
+  /** Mock fetch: serve `manifestBytes` for SHA256SUMS, its signature for *.sig. */
+  function mockManifest(manifestBytes: Uint8Array, sigBytes = sign(manifestBytes)) {
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = typeof input === "string" ? input : (input as URL).toString();
+      const out = url.endsWith(".sig") ? sigBytes : manifestBytes;
+      return { ok: true, arrayBuffer: async () => out.buffer } as Response;
+    });
+  }
+
+  const body = (lines: string, version = PRO_VERSION) =>
+    enc(`version=${version}\n${lines}`);
+
+  it("passes when signature is valid and hash matches", async () => {
+    const data = Buffer.from("the real pro binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    mockManifest(body(`${hash}  ${getArchiveName()}\n`));
+    await expect(verifyProDownload(file, PRO_VERSION)).resolves.toBeUndefined();
+  });
+
+  it("CLOAKBROWSER_SKIP_CHECKSUM does NOT bypass Pro verification", async () => {
+    const file = tmpFile(Buffer.from("a malicious pro binary"));
+    const goodHash = createHash("sha256").update(Buffer.from("the real pro binary")).digest("hex");
+    process.env.CLOAKBROWSER_SKIP_CHECKSUM = "true";
+    mockManifest(body(`${goodHash}  ${getArchiveName()}\n`));
+    const err = await verifyProDownload(file, PRO_VERSION).catch((e) => e);
+    // The error TYPE is the contract the ensureBinary router branches on:
+    // BinaryVerificationError => re-throw (never downgrade to free).
+    expect(err).toBeInstanceOf(BinaryVerificationError);
+    expect(err.message).toMatch(/Checksum verification failed/);
+  });
+
+  it("treats a failed manifest fetch as transient, not tampering", async () => {
+    // A failed manifest FETCH must be a plain Error (router falls back to free),
+    // NOT a BinaryVerificationError (which the router re-throws as a hard fail).
+    const file = tmpFile(Buffer.from("x"));
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({ ok: false, status: 404 } as Response);
+    const err = await verifyProDownload(file, PRO_VERSION).catch((e) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect(err).not.toBeInstanceOf(BinaryVerificationError);
+  });
+
+  it("fails on a signed manifest for the wrong version (downgrade)", async () => {
+    const data = Buffer.from("the real pro binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    mockManifest(body(`${hash}  ${getArchiveName()}\n`, "1.0.0.0"));
+    const err = await verifyProDownload(file, PRO_VERSION).catch((e) => e);
+    expect(err).toBeInstanceOf(BinaryVerificationError);
+    expect(err.message).toMatch(/Version mismatch/);
+  });
+
+  it("rejects a manifest tampered after signing", async () => {
+    const data = Buffer.from("the real pro binary");
+    const file = tmpFile(data);
+    const hash = createHash("sha256").update(data).digest("hex");
+    const good = body(`${hash}  ${getArchiveName()}\n`);
+    const sig = sign(good);
+    const tampered = enc(new TextDecoder().decode(good).replace(getArchiveName(), "evil.tar.gz"));
+    mockManifest(tampered, sig);
+    const err = await verifyProDownload(file, PRO_VERSION).catch((e) => e);
+    expect(err).toBeInstanceOf(BinaryVerificationError);
+    expect(err.message).toMatch(/signature verification failed/);
+  });
+});
+
+describe("version binding", () => {
+  it("reads the version= line", () => {
+    expect(
+      parseManifestVersion("version=146.0.7680.177.5\nabc  file.tar.gz\n")
+    ).toBe("146.0.7680.177.5");
+  });
+
+  it("returns null when absent", () => {
+    expect(parseManifestVersion("abc  file.tar.gz\n")).toBeNull();
+  });
+
+  it("old parseChecksums ignores the version line", () => {
+    const result = parseChecksums(
+      `version=146.0.7680.177.5\n${"a".repeat(64)}  cloakbrowser-linux-x64.tar.gz\n`
+    );
+    expect(result.size).toBe(1);
+    expect(result.has("cloakbrowser-linux-x64.tar.gz")).toBe(true);
+  });
+});
+
+describe("fetchSignedManifest", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const mockPair = (manifest: string, sig: string, failPrimarySig = false) =>
+    vi.spyOn(globalThis, "fetch").mockImplementation(async (input) => {
+      const url = typeof input === "string" ? input : (input as URL).toString();
+      const isSig = url.endsWith(".sig");
+      if (url.includes("cloakbrowser.dev") && isSig && failPrimarySig) {
+        return { ok: false, status: 404 } as Response;
+      }
+      return {
+        ok: true,
+        arrayBuffer: async () =>
+          new TextEncoder().encode(isSig ? sig : manifest).buffer,
+      } as Response;
+    });
+
+  it("returns manifest + sig from the primary origin", async () => {
+    mockPair("MANIFEST", "U0lH");
+    const result = await fetchSignedManifest("1.2.3.4");
+    expect(new TextDecoder().decode(result!.manifestBytes)).toBe("MANIFEST");
+    expect(new TextDecoder().decode(result!.sigBytes)).toBe("U0lH");
+  });
+
+  it("falls back to GitHub when the primary .sig is missing", async () => {
+    const spy = mockPair("MANIFEST", "U0lH", true);
+    const result = await fetchSignedManifest("1.2.3.4");
+    expect(result).not.toBeNull();
+    // primary SHA256SUMS + primary .sig (404) + github SHA256SUMS + github .sig
+    expect(spy.mock.calls.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("returns null when everything fails", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("network"));
+    expect(await fetchSignedManifest("1.2.3.4")).toBeNull();
+  });
+});

pyproject.toml

@@ -51,11 +51,11 @@ classifiers = [
 dependencies = [
     "playwright>=1.40",
     "httpx>=0.24",
+    "cryptography>=41.0",  # verify Ed25519 signature on SHA256SUMS before trusting it
 ]
 
 [project.optional-dependencies]
 geoip = ["geoip2>=4.0", "socksio>=1.0"]  # socksio: SOCKS5 transport for httpx
-patchright = ["patchright>=1.40"]
 serve = ["aiohttp>=3.9", "websockets>=12.0"]
 dev = ["pytest>=7.0", "pytest-asyncio>=0.23"]
 

tests/conftest.py

@@ -1,11 +0,0 @@
-"""Shared test fixtures."""
-
-import os
-
-import pytest
-
-
-@pytest.fixture(autouse=True)
-def _clean_backend_env(monkeypatch):
-    """Ensure CLOAKBROWSER_BACKEND doesn't leak into tests from the host environment."""
-    monkeypatch.delenv("CLOAKBROWSER_BACKEND", raising=False)

tests/test_backend.py

@@ -1,45 +0,0 @@
-"""Unit tests for backend resolution (_resolve_backend)."""
-
-import os
-from unittest.mock import patch
-
-import pytest
-
-from cloakbrowser.browser import _resolve_backend
-
-
-def test_resolve_backend_default():
-    """No param, no env var → 'playwright'."""
-    with patch.dict(os.environ, {}, clear=True):
-        assert _resolve_backend(None) == "playwright"
-
-
-def test_resolve_backend_explicit_playwright():
-    assert _resolve_backend("playwright") == "playwright"
-
-
-def test_resolve_backend_explicit_patchright():
-    assert _resolve_backend("patchright") == "patchright"
-
-
-def test_resolve_backend_env_var():
-    """CLOAKBROWSER_BACKEND env var used when no param."""
-    with patch.dict(os.environ, {"CLOAKBROWSER_BACKEND": "patchright"}):
-        assert _resolve_backend(None) == "patchright"
-
-
-def test_resolve_backend_param_beats_env():
-    """Explicit param overrides env var."""
-    with patch.dict(os.environ, {"CLOAKBROWSER_BACKEND": "patchright"}):
-        assert _resolve_backend("playwright") == "playwright"
-
-
-def test_resolve_backend_invalid_raises():
-    with pytest.raises(ValueError, match="Unknown backend 'bogus'"):
-        _resolve_backend("bogus")
-
-
-def test_resolve_backend_invalid_env_raises():
-    with patch.dict(os.environ, {"CLOAKBROWSER_BACKEND": "bogus"}):
-        with pytest.raises(ValueError, match="Unknown backend 'bogus'"):
-            _resolve_backend(None)

tests/test_extension_loading.py

@@ -5,8 +5,8 @@ from cloakbrowser import launch
 
 
 @patch("cloakbrowser.browser.ensure_binary")
-@patch("cloakbrowser.browser._import_sync_playwright")
-def test_extension_loading(mock_playwright_import, mock_ensure_binary):
+@patch("playwright.sync_api.sync_playwright")
+def test_extension_loading(mock_sync_playwright, mock_ensure_binary):
     mock_ensure_binary.return_value = "/fake/chrome"
 
     mock_browser = MagicMock()
@@ -14,10 +14,7 @@ def test_extension_loading(mock_playwright_import, mock_ensure_binary):
     mock_pw = MagicMock()
     mock_pw.chromium.launch.return_value = mock_browser
 
-    mock_pw_manager = MagicMock()
-    mock_pw_manager.return_value.start.return_value = mock_pw
-
-    mock_playwright_import.return_value = mock_pw_manager
+    mock_sync_playwright.return_value.start.return_value = mock_pw
 
     launch(extension_paths=["./ext"])
 

tests/test_launch.py

@@ -1,10 +1,33 @@
 """Basic launch tests for cloakbrowser."""
 
 import pytest
-from cloakbrowser import launch, launch_async, binary_info
+from cloakbrowser import (
+    launch,
+    launch_async,
+    launch_context,
+    launch_persistent_context,
+    binary_info,
+)
 from cloakbrowser.config import get_chromium_version
 
 
+@pytest.mark.parametrize("env", [None, "patchright"])
+def test_removed_backend_kwarg_raises(env, monkeypatch):
+    """The removed `backend` parameter raises a clear TypeError before any
+    launch side effects, regardless of the (also removed) CLOAKBROWSER_BACKEND
+    env var. Guards the patchright removal."""
+    if env is None:
+        monkeypatch.delenv("CLOAKBROWSER_BACKEND", raising=False)
+    else:
+        monkeypatch.setenv("CLOAKBROWSER_BACKEND", env)
+    with pytest.raises(TypeError, match="backend"):
+        launch(backend="patchright")
+    with pytest.raises(TypeError, match="backend"):
+        launch_context(backend="patchright")
+    with pytest.raises(TypeError, match="backend"):
+        launch_persistent_context("/tmp/cloakbrowser-test-profile", backend="patchright")
+
+
 def test_binary_info():
     """binary_info() returns expected structure."""
     info = binary_info()

tests/test_launch_context.py

@@ -33,6 +33,82 @@ def test_default_viewport(mock_launch, _mock_bin):
     assert ctx_kwargs[1]["viewport"] == DEFAULT_VIEWPORT
 
 
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch")
+def test_headed_no_viewport(mock_launch, _mock_bin):
+    """Headed (headless=False): no emulated viewport — no_viewport=True so the page
+    tracks the real window (CDP viewport emulation would force outerWidth < innerWidth)."""
+    browser, context = _make_mock_browser()
+    mock_launch.return_value = browser
+
+    from cloakbrowser.browser import launch_context
+    launch_context(headless=False)
+
+    ctx_kwargs = browser.new_context.call_args[1]
+    assert ctx_kwargs.get("no_viewport") is True
+    assert "viewport" not in ctx_kwargs
+
+
+def test_default_no_viewport_helper():
+    """_default_no_viewport defaults new_page()/new_context() to no_viewport=True,
+    but never overrides an explicit viewport (Playwright rejects passing both)."""
+    from cloakbrowser.browser import _default_no_viewport
+
+    browser = MagicMock()
+    orig_new_page = browser.new_page
+    orig_new_context = browser.new_context
+    _default_no_viewport(browser)
+
+    browser.new_page()
+    orig_new_page.assert_called_once_with(no_viewport=True)
+    browser.new_context()
+    orig_new_context.assert_called_once_with(no_viewport=True)
+
+    # Explicit viewport respected — no_viewport NOT injected.
+    orig_new_page.reset_mock()
+    browser.new_page(viewport={"width": 800, "height": 600})
+    orig_new_page.assert_called_once_with(viewport={"width": 800, "height": 600})
+
+
+@pytest.mark.asyncio
+async def test_default_no_viewport_helper_async():
+    """_default_no_viewport_async mirrors the sync helper for async new_page/new_context."""
+    from cloakbrowser.browser import _default_no_viewport_async
+
+    browser = MagicMock()
+    browser.new_page = AsyncMock()
+    browser.new_context = AsyncMock()
+    orig_new_page = browser.new_page
+    orig_new_context = browser.new_context
+    _default_no_viewport_async(browser)
+
+    await browser.new_page()
+    orig_new_page.assert_awaited_once_with(no_viewport=True)
+    await browser.new_context()
+    orig_new_context.assert_awaited_once_with(no_viewport=True)
+
+    # Explicit viewport respected — no_viewport NOT injected.
+    orig_new_page.reset_mock()
+    await browser.new_page(viewport={"width": 800, "height": 600})
+    orig_new_page.assert_awaited_once_with(viewport={"width": 800, "height": 600})
+
+
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.launch")
+def test_conflicting_viewport_kwargs_deduped(mock_launch, _mock_bin):
+    """If a caller forces no_viewport via **kwargs alongside viewport=, only one
+    reaches Playwright (which rejects both). The explicit kwargs value wins."""
+    browser, context = _make_mock_browser()
+    mock_launch.return_value = browser
+
+    from cloakbrowser.browser import launch_context
+    launch_context(viewport={"width": 1280, "height": 800}, no_viewport=True)
+
+    ctx_kwargs = browser.new_context.call_args[1]
+    assert ctx_kwargs.get("no_viewport") is True
+    assert "viewport" not in ctx_kwargs
+
+
 @patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
 @patch("cloakbrowser.browser.launch")
 def test_custom_viewport(mock_launch, _mock_bin):

tests/test_license.py

@@ -0,0 +1,408 @@
+"""Tests for the CloakBrowser Pro license module."""
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from cloakbrowser.download import BinaryVerificationError, ensure_binary
+from cloakbrowser.license import (
+    LicenseInfo,
+    get_pro_latest_version,
+    resolve_license_key,
+    validate_license,
+)
+
+
+# ── resolve_license_key ───────────────────────────────
+
+
+class TestResolveLicenseKey:
+    def test_explicit_param_wins(self):
+        with patch.dict(os.environ, {"CLOAKBROWSER_LICENSE_KEY": "env-key"}):
+            assert resolve_license_key("explicit") == "explicit"
+
+    def test_env_var_fallback(self):
+        with patch.dict(os.environ, {"CLOAKBROWSER_LICENSE_KEY": "env-key"}):
+            assert resolve_license_key() == "env-key"
+
+    def test_returns_none_when_absent(self):
+        with patch.dict(os.environ, {}, clear=True):
+            os.environ.pop("CLOAKBROWSER_LICENSE_KEY", None)
+            assert resolve_license_key() is None
+
+    def test_empty_string_param_uses_env(self):
+        with patch.dict(os.environ, {"CLOAKBROWSER_LICENSE_KEY": "env-key"}):
+            assert resolve_license_key("") == "env-key"
+
+    def test_file_fallback(self, tmp_path):
+        key_file = tmp_path / "license.key"
+        key_file.write_text("file-key-123\n")
+        with patch.dict(os.environ, {}, clear=True):
+            os.environ.pop("CLOAKBROWSER_LICENSE_KEY", None)
+            with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+                assert resolve_license_key() == "file-key-123"
+
+    def test_env_takes_precedence_over_file(self, tmp_path):
+        key_file = tmp_path / "license.key"
+        key_file.write_text("file-key")
+        with patch.dict(os.environ, {"CLOAKBROWSER_LICENSE_KEY": "env-key"}):
+            with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+                assert resolve_license_key() == "env-key"
+
+    def test_no_file_returns_none(self, tmp_path):
+        with patch.dict(os.environ, {}, clear=True):
+            os.environ.pop("CLOAKBROWSER_LICENSE_KEY", None)
+            with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+                assert resolve_license_key() is None
+
+
+# ── validate_license ──────────────────────────────────
+
+
+class TestValidateLicense:
+    def test_fresh_cache_skips_server(self, tmp_path):
+        cache_path = tmp_path / ".license_cache"
+        key_sha = hashlib.sha256(b"test-key").hexdigest()
+        cache_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": True,
+            "plan": "team",
+            "expires": "2026-12-01",
+            "validated_at": time.time(),
+        }))
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post") as mock_post:
+                result = validate_license("test-key")
+
+        mock_post.assert_not_called()
+        assert result is not None
+        assert result.valid is True
+        assert result.plan == "team"
+
+    def test_stale_cache_calls_server(self, tmp_path):
+        cache_path = tmp_path / ".license_cache"
+        key_sha = hashlib.sha256(b"test-key").hexdigest()
+        cache_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": True,
+            "plan": "solo",
+            "expires": None,
+            "validated_at": time.time() - 90000,  # 25 hours ago
+        }))
+
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"valid": True, "plan": "solo", "expires": None}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", return_value=mock_resp) as mock_post:
+                result = validate_license("test-key")
+
+        mock_post.assert_called_once()
+        assert result is not None
+        assert result.valid is True
+
+    def test_server_success(self, tmp_path):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"valid": True, "plan": "business", "expires": "2026-07-13"}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", return_value=mock_resp):
+                result = validate_license("pro-key")
+
+        assert result is not None
+        assert result.valid is True
+        assert result.plan == "business"
+        assert result.expires == "2026-07-13"
+
+    def test_server_rejection(self, tmp_path):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"valid": False, "plan": "solo", "expires": None}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", return_value=mock_resp):
+                result = validate_license("bad-key")
+
+        assert result is not None
+        assert result.valid is False
+
+    def test_server_unreachable_uses_stale_cache(self, tmp_path):
+        cache_path = tmp_path / ".license_cache"
+        key_sha = hashlib.sha256(b"test-key").hexdigest()
+        cache_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": True,
+            "plan": "solo",
+            "expires": "2026-12-01",
+            "validated_at": time.time() - 90000,
+        }))
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", side_effect=Exception("timeout")):
+                result = validate_license("test-key")
+
+        assert result is not None
+        assert result.valid is True
+
+    def test_server_unreachable_no_cache_returns_none(self, tmp_path):
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", side_effect=Exception("timeout")):
+                result = validate_license("test-key")
+
+        assert result is None
+
+    def test_cache_stores_hash_not_raw_key(self, tmp_path):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"valid": True, "plan": "solo", "expires": None}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", return_value=mock_resp):
+                validate_license("secret-key-123")
+
+        cache_path = tmp_path / ".license_cache"
+        content = cache_path.read_text()
+        assert "secret-key-123" not in content
+        expected_sha = hashlib.sha256(b"secret-key-123").hexdigest()
+        assert expected_sha in content
+
+    def test_expired_license_rejected_from_cache(self, tmp_path):
+        cache_path = tmp_path / ".license_cache"
+        key_sha = hashlib.sha256(b"test-key").hexdigest()
+        cache_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": True,
+            "plan": "solo",
+            "expires": "2020-01-01T00:00:00+00:00",
+            "validated_at": time.time(),
+        }))
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            result = validate_license("test-key")
+
+        assert result is not None
+        assert result.valid is False
+
+    def test_expired_license_naive_date_rejected(self, tmp_path):
+        """Date-only string (naive datetime) should also be detected as expired."""
+        cache_path = tmp_path / ".license_cache"
+        key_sha = hashlib.sha256(b"test-key").hexdigest()
+        cache_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": True,
+            "plan": "solo",
+            "expires": "2020-01-01",
+            "validated_at": time.time(),
+        }))
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            result = validate_license("test-key")
+
+        assert result is not None
+        assert result.valid is False
+
+    def test_wrong_key_cache_ignored(self, tmp_path):
+        cache_path = tmp_path / ".license_cache"
+        cache_path.write_text(json.dumps({
+            "key_sha256": "other-hash",
+            "valid": True,
+            "plan": "solo",
+            "expires": None,
+            "validated_at": time.time(),
+        }))
+
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"valid": True, "plan": "solo", "expires": None}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", return_value=mock_resp) as mock_post:
+                validate_license("different-key")
+
+        mock_post.assert_called_once()
+
+    def test_corrupted_validated_at_does_not_crash(self, tmp_path):
+        """A non-numeric validated_at must be treated as an absent cache, not crash."""
+        cache_path = tmp_path / ".license_cache"
+        key_sha = hashlib.sha256(b"test-key").hexdigest()
+        cache_path.write_text(json.dumps({
+            "key_sha256": key_sha,
+            "valid": True,
+            "plan": "solo",
+            "expires": None,
+            "validated_at": "not-a-number",
+        }))
+
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"valid": True, "plan": "solo", "expires": None}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.post", return_value=mock_resp) as mock_post:
+                result = validate_license("test-key")
+
+        mock_post.assert_called_once()  # corrupted cache ignored → server hit
+        assert result is not None
+        assert result.valid is True
+
+
+# ── get_pro_latest_version ────────────────────────────
+
+
+class TestGetProLatestVersion:
+    def test_fetches_version(self, tmp_path):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = {"version": "147.0.1234.5"}
+        mock_resp.raise_for_status = MagicMock()
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.get", return_value=mock_resp):
+                version = get_pro_latest_version()
+
+        assert version == "147.0.1234.5"
+
+    def test_rate_limited(self, tmp_path):
+        marker = tmp_path / ".last_pro_version_check"
+        marker.write_text("147.0.1234.5")
+
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.get") as mock_get:
+                version = get_pro_latest_version()
+
+        mock_get.assert_not_called()
+        assert version == "147.0.1234.5"
+
+    def test_network_error_returns_none(self, tmp_path):
+        with patch("cloakbrowser.license.get_cache_dir", return_value=tmp_path):
+            with patch("cloakbrowser.license.httpx.get", side_effect=Exception("network")):
+                version = get_pro_latest_version()
+
+        assert version is None
+
+
+# ── Config pro parameter ──────────────────────────────
+
+
+class TestConfigPro:
+    def test_binary_dir_pro_suffix(self, tmp_path):
+        from cloakbrowser.config import get_binary_dir
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_CACHE_DIR": str(tmp_path)}):
+            normal = get_binary_dir("147.0.0.0")
+            pro = get_binary_dir("147.0.0.0", pro=True)
+
+        assert str(normal).endswith("chromium-147.0.0.0")
+        assert str(pro).endswith("chromium-147.0.0.0-pro")
+
+    def test_binary_dir_default_no_suffix(self, tmp_path):
+        from cloakbrowser.config import get_binary_dir
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_CACHE_DIR": str(tmp_path)}):
+            normal = get_binary_dir("147.0.0.0")
+
+        assert not str(normal).endswith("-pro")
+
+    def test_effective_version_pro_marker(self, tmp_path):
+        from cloakbrowser.config import get_effective_version, get_platform_tag
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_CACHE_DIR": str(tmp_path)}):
+            tag = get_platform_tag()
+            marker = tmp_path / f"latest_pro_version_{tag}"
+            marker.write_text("147.0.5555.1")
+
+            # Create the binary so effective version returns it
+            from cloakbrowser.config import get_binary_path
+            bp = get_binary_path("147.0.5555.1", pro=True)
+            bp.parent.mkdir(parents=True, exist_ok=True)
+            bp.write_text("fake")
+
+            version = get_effective_version(pro=True)
+
+        assert version == "147.0.5555.1"
+
+
+# ── binary_info tier reporting ────────────────────────
+
+
+class TestBinaryInfoTier:
+    """binary_info() reports tier from the binary actually on disk — NOT from a
+    cached license, which can disagree with what's installed or the active key."""
+
+    def test_free_when_no_pro_binary_even_if_license_cached(self, tmp_path):
+        from cloakbrowser.download import binary_info
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_CACHE_DIR": str(tmp_path)}, clear=False):
+            # A valid, fresh license is cached...
+            (tmp_path / ".license_cache").write_text(json.dumps({
+                "key_sha256": hashlib.sha256(b"cb_x").hexdigest(),
+                "valid": True, "plan": "solo", "expires": None,
+                "validated_at": time.time(),
+            }))
+            # ...but no Pro binary is on disk → must report free, not pro.
+            info = binary_info()
+
+        assert info["tier"] == "free"
+
+    def test_pro_when_pro_binary_installed(self, tmp_path):
+        from cloakbrowser.config import get_binary_path, get_platform_tag
+        from cloakbrowser.download import binary_info
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_CACHE_DIR": str(tmp_path)}, clear=False):
+            tag = get_platform_tag()
+            (tmp_path / f"latest_pro_version_{tag}").write_text("147.0.5555.1")
+            bp = get_binary_path("147.0.5555.1", pro=True)
+            bp.parent.mkdir(parents=True, exist_ok=True)
+            bp.write_text("fake")
+            bp.chmod(0o755)
+            info = binary_info()
+
+        assert info["tier"] == "pro"
+        assert info["version"] == "147.0.5555.1"
+
+
+# ── ensure_binary Pro routing (fail-closed vs fall-back) ──────────────────────
+
+
+class TestEnsureBinaryProRouting:
+    """A valid-license user is NEVER silently downgraded to the free binary. Both
+    a tampering signal (verification failure) and a transient failure
+    (network/server) surface a clear error — they differ only in the message:
+    tampering is re-raised verbatim (security, no 'retry'); transient is rewrapped
+    as an actionable 'Pro binary unavailable, retry' error carrying the cause."""
+
+    def test_verification_failure_propagates_verbatim(self):
+        """A BinaryVerificationError must surface verbatim — never reach free."""
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}, clear=False), \
+             patch("cloakbrowser.download.get_local_binary_override", return_value=None), \
+             patch("cloakbrowser.license.resolve_license_key", return_value="cb_x"), \
+             patch("cloakbrowser.license.validate_license",
+                   return_value=LicenseInfo(valid=True, plan="solo", expires=None)), \
+             patch("cloakbrowser.download._ensure_pro_binary",
+                   side_effect=BinaryVerificationError("bad signature")), \
+             patch("cloakbrowser.download.check_platform_available",
+                   side_effect=AssertionError("MUST NOT reach the free-tier path")):
+            with pytest.raises(BinaryVerificationError, match="bad signature"):
+                ensure_binary("cb_x")
+
+    def test_transient_failure_hard_errors_not_free(self):
+        """A transient Pro failure must surface a clear, actionable error carrying
+        the underlying cause — NOT silently download the free binary."""
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}, clear=False), \
+             patch("cloakbrowser.download.get_local_binary_override", return_value=None), \
+             patch("cloakbrowser.license.resolve_license_key", return_value="cb_x"), \
+             patch("cloakbrowser.license.validate_license",
+                   return_value=LicenseInfo(valid=True, plan="solo", expires=None)), \
+             patch("cloakbrowser.download._ensure_pro_binary",
+                   side_effect=RuntimeError("network blip")), \
+             patch("cloakbrowser.download.check_platform_available",
+                   side_effect=AssertionError("MUST NOT reach the free-tier path")):
+            with pytest.raises(RuntimeError, match="Pro binary unavailable: network blip"):
+                ensure_binary("cb_x")

tests/test_persistent_context.py

@@ -55,6 +55,22 @@ def test_persistent_context_default_viewport(_mock_geoip, _mock_bin):
     assert call_kwargs["viewport"] == DEFAULT_VIEWPORT
 
 
+@patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
+@patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
+def test_persistent_context_headed_no_viewport(_mock_geoip, _mock_bin):
+    """Headed (headless=False): no_viewport=True instead of DEFAULT_VIEWPORT so the
+    page tracks the real window (avoids the outerWidth < innerWidth tell)."""
+    pw_cm, pw, context = _make_mock_pw_and_context()
+
+    with patch("playwright.sync_api.sync_playwright", return_value=pw_cm):
+        from cloakbrowser.browser import launch_persistent_context
+        launch_persistent_context("/tmp/profile", headless=False)
+
+    call_kwargs = pw.chromium.launch_persistent_context.call_args[1]
+    assert call_kwargs.get("no_viewport") is True
+    assert "viewport" not in call_kwargs
+
+
 @patch("cloakbrowser.browser.ensure_binary", return_value="/fake/chrome")
 @patch("cloakbrowser.browser.maybe_resolve_geoip", return_value=(None, None, None))
 def test_persistent_context_custom_viewport(_mock_geoip, _mock_bin):

tests/test_stealth.py

@@ -259,9 +259,8 @@ class TestIssueRegressions:
     def test_add_init_script_with_proxy(self, browser):
         """Issue #27: add_init_script + proxy must not cause ERR_TUNNEL_CONNECTION_FAILED.
 
-        Patchright bug: add_init_script breaks proxy auth. This test guards
-        against regression if/when the upstream fix lands. Uses context-level
-        proxy to avoid launching a separate browser (event loop conflict).
+        Uses context-level proxy to avoid launching a separate browser
+        (event loop conflict).
         """
         proxy = os.environ.get("CLOAKBROWSER_TEST_PROXY")
         if not proxy:
@@ -276,11 +275,6 @@ class TestIssueRegressions:
             val = page.evaluate("window.__cloaktest")
             assert val == 99, f"init_script value wrong: {val}"
             assert "origin" in body, f"Page didn't load through proxy: {body[:100]}"
-        except Exception as e:
-            err = str(e)
-            if "ERR_TUNNEL_CONNECTION_FAILED" in err:
-                pytest.xfail("Known patchright bug: add_init_script + proxy auth (issue #27)")
-            raise
         finally:
             page.close()
             ctx.close()

tests/test_update.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+import base64
 import hashlib
 import os
 from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 
 from cloakbrowser.config import (
     CHROMIUM_VERSION,
@@ -19,13 +21,20 @@ from cloakbrowser.config import (
     get_platform_tag,
 )
 from cloakbrowser.download import (
+    BinaryVerificationError,
     _check_wrapper_update,
     _download_and_extract,
+    _download_pro_binary,
     _fetch_checksums,
+    _fetch_signed_manifest,
     _get_latest_chromium_version,
     _parse_checksums,
+    _parse_manifest_version,
     _should_check_for_update,
     _verify_checksum,
+    _verify_download_checksum,
+    _verify_pro_download,
+    _verify_signature,
     _write_version_marker,
     check_for_update,
     clear_cache,
@@ -486,7 +495,6 @@ class TestDownloadFallback:
         with patch.dict(os.environ, {
             "CLOAKBROWSER_CACHE_DIR": str(tmp_path),
             "CLOAKBROWSER_DOWNLOAD_URL": "",
-            "CLOAKBROWSER_SKIP_CHECKSUM": "true",
         }):
             urls_called = []
 
@@ -497,7 +505,10 @@ class TestDownloadFallback:
                 # GitHub fallback succeeds
                 dest.write_bytes(b"fake")
 
+            # This test exercises URL fallback, not verification — stub the
+            # (now signature-based, non-bypassable) verify step.
             with patch("cloakbrowser.download._download_file", side_effect=mock_download_file), \
+                 patch("cloakbrowser.download._verify_download_checksum"), \
                  patch("cloakbrowser.download._extract_archive"), \
                  patch("cloakbrowser.download._show_welcome"):
                 _download_and_extract()
@@ -548,3 +559,347 @@ class TestDownloadFallback:
                 result = _fetch_checksums()
 
         assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Signed-manifest verification (Ed25519). Trust root is the pinned public key,
+# not the same-origin SHA256SUMS — this is what closes M1 (#308).
+# ---------------------------------------------------------------------------
+def _make_key():
+    priv = Ed25519PrivateKey.generate()
+    from cryptography.hazmat.primitives import serialization
+
+    raw = priv.public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+    return priv, base64.b64encode(raw).decode()
+
+
+def _sign(priv, manifest_bytes: bytes) -> bytes:
+    """Return SHA256SUMS.sig content (base64 of the raw signature), as served."""
+    return base64.b64encode(priv.sign(manifest_bytes))
+
+
+class TestSignatureVerification:
+    """_verify_signature: the cryptographic gate over the raw manifest bytes."""
+
+    def test_valid_signature_passes(self):
+        priv, pub_b64 = _make_key()
+        manifest = b"abc  cloakbrowser-linux-x64.tar.gz\n"
+        sig = _sign(priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]):
+            _verify_signature(manifest, sig)  # no raise
+
+    def test_tampered_manifest_fails(self):
+        priv, pub_b64 = _make_key()
+        manifest = b"abc  cloakbrowser-linux-x64.tar.gz\n"
+        sig = _sign(priv, manifest)
+        tampered = manifest.replace(b"abc", b"xyz")
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]):
+            with pytest.raises(RuntimeError, match="signature verification failed"):
+                _verify_signature(tampered, sig)
+
+    def test_wrong_key_fails(self):
+        priv, _ = _make_key()
+        _, other_pub = _make_key()
+        manifest = b"data\n"
+        sig = _sign(priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [other_pub]):
+            with pytest.raises(RuntimeError, match="signature verification failed"):
+                _verify_signature(manifest, sig)
+
+    def test_malformed_signature_fails(self):
+        _, pub_b64 = _make_key()
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]):
+            with pytest.raises(RuntimeError, match="Malformed"):
+                _verify_signature(b"data\n", b"!!!not base64!!!")
+
+    def test_placeholder_key_is_skipped_not_crashing(self):
+        """An unparseable pinned key (placeholder) must not abort — a real key still validates."""
+        priv, pub_b64 = _make_key()
+        manifest = b"data\n"
+        sig = _sign(priv, manifest)
+        with patch(
+            "cloakbrowser.download.BINARY_SIGNING_PUBKEYS",
+            ["REPLACE_WITH_REAL_ED25519_PUBLIC_KEY_BASE64", pub_b64],
+        ):
+            _verify_signature(manifest, sig)  # no raise
+
+    def test_key_rotation_second_key_accepts(self):
+        """A manifest signed with the new key validates while the old key stays pinned."""
+        old_priv, old_pub = _make_key()
+        new_priv, new_pub = _make_key()
+        manifest = b"rotated\n"
+        sig = _sign(new_priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [old_pub, new_pub]):
+            _verify_signature(manifest, sig)  # no raise
+
+
+class TestVerifyDownloadChecksumSigned:
+    """_verify_download_checksum on the official path: signature + version + hash, fail-closed."""
+
+    def _hash(self, data: bytes) -> str:
+        return hashlib.sha256(data).hexdigest()
+
+    def _manifest(self, body: str, version: str | None = None) -> bytes:
+        """Build a signed-manifest body with the bound version line prepended."""
+        v = version if version is not None else get_chromium_version()
+        return f"version={v}\n{body}".encode()
+
+    def test_valid_manifest_and_hash_passes(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real binary")
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        manifest = self._manifest(f"{self._hash(b'the real binary')}  {tarball}\n")
+        sig = _sign(priv, manifest)
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            _verify_download_checksum(archive)  # no raise
+
+    def test_tampered_binary_fails_hash(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"a malicious binary")  # different bytes
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        manifest = self._manifest(f"{self._hash(b'the real binary')}  {tarball}\n")
+        sig = _sign(priv, manifest)
+
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Checksum verification failed"):
+                _verify_download_checksum(archive)
+
+    def test_wrong_version_fails_downgrade(self, tmp_path):
+        """A genuinely-signed manifest for a DIFFERENT version is rejected (downgrade)."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real binary")
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        # Manifest declares an old version, but we ask for get_chromium_version().
+        manifest = self._manifest(
+            f"{self._hash(b'the real binary')}  {tarball}\n", version="1.0.0.0"
+        )
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Version mismatch"):
+                _verify_download_checksum(archive)
+
+    def test_missing_version_line_fails(self, tmp_path):
+        """A signed manifest without a version line is rejected (binding required)."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real binary")
+        tarball = get_download_url().rsplit("/", 1)[-1]
+        manifest = f"{self._hash(b'the real binary')}  {tarball}\n".encode()  # no version=
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Version mismatch"):
+                _verify_download_checksum(archive)
+
+    def test_missing_signed_manifest_fails_closed(self, tmp_path):
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=None):
+            with pytest.raises(RuntimeError, match="signed SHA256SUMS"):
+                _verify_download_checksum(archive)
+
+    def test_manifest_without_entry_fails(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        manifest = self._manifest("deadbeef  some-other-file.tar.gz\n")  # no entry for our tarball
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_DOWNLOAD_URL": ""}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download._fetch_signed_manifest", return_value=(manifest, sig)):
+            with pytest.raises(RuntimeError, match="no entry for"):
+                _verify_download_checksum(archive)
+
+    def test_custom_url_uses_plain_checksum_and_skip(self, tmp_path):
+        """Self-hosted CLOAKBROWSER_DOWNLOAD_URL keeps the legacy skippable path."""
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        with patch.dict(os.environ, {
+            "CLOAKBROWSER_DOWNLOAD_URL": "https://my-mirror.test",
+            "CLOAKBROWSER_SKIP_CHECKSUM": "true",
+        }):
+            # Signature path must NOT be consulted for a custom mirror.
+            with patch("cloakbrowser.download._fetch_signed_manifest") as mocked:
+                _verify_download_checksum(archive)  # skip honored, no raise
+            mocked.assert_not_called()
+
+
+class TestVerifyProDownloadSigned:
+    """_verify_pro_download: Pro binaries get the SAME non-bypassable signature
+    check as the free official path (parity — closes the Pro M1 gap)."""
+
+    PRO_VERSION = "147.0.1.0"
+
+    def _hash(self, data: bytes) -> str:
+        return hashlib.sha256(data).hexdigest()
+
+    def _tarball(self) -> str:
+        return get_download_url().rsplit("/", 1)[-1]
+
+    def _mock_fetch(self, manifest: bytes, sig: bytes):
+        """httpx.get stub: returns the .sig for *.sig URLs, manifest otherwise."""
+        def mock_get(url, **kwargs):
+            resp = MagicMock()
+            resp.raise_for_status = MagicMock()
+            resp.content = sig if url.endswith(".sig") else manifest
+            return resp
+        return mock_get
+
+    def test_valid_pro_manifest_passes(self, tmp_path):
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real pro binary")
+        manifest = (
+            f"version={self.PRO_VERSION}\n"
+            f"{self._hash(b'the real pro binary')}  {self._tarball()}\n"
+        ).encode()
+        sig = _sign(priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download.httpx.get", side_effect=self._mock_fetch(manifest, sig)):
+            _verify_pro_download(archive, self.PRO_VERSION)  # no raise
+
+    def test_skip_checksum_does_not_bypass(self, tmp_path):
+        """CLOAKBROWSER_SKIP_CHECKSUM must NOT weaken Pro verification (the point)."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"a malicious pro binary")  # bytes differ from manifest
+        manifest = (
+            f"version={self.PRO_VERSION}\n"
+            f"{self._hash(b'the real pro binary')}  {self._tarball()}\n"
+        ).encode()
+        sig = _sign(priv, manifest)
+        with patch.dict(os.environ, {"CLOAKBROWSER_SKIP_CHECKSUM": "true"}), \
+             patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download.httpx.get", side_effect=self._mock_fetch(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Checksum verification failed"):
+                _verify_pro_download(archive, self.PRO_VERSION)
+
+    def test_missing_manifest_is_transient_not_tampering(self, tmp_path):
+        """A failed manifest FETCH is transient (router falls back to free), so it
+        must be a plain RuntimeError — NOT a BinaryVerificationError, which the
+        router re-raises as a hard failure."""
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"x")
+        with patch("cloakbrowser.download.httpx.get", side_effect=Exception("404")):
+            with pytest.raises(RuntimeError) as ei:
+                _verify_pro_download(archive, self.PRO_VERSION)
+        assert not isinstance(ei.value, BinaryVerificationError)
+
+    def test_wrong_version_fails_downgrade(self, tmp_path):
+        """A genuinely-signed Pro manifest for a DIFFERENT version is rejected."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real pro binary")
+        manifest = (
+            f"version=1.0.0.0\n"  # declares old version, we ask for PRO_VERSION
+            f"{self._hash(b'the real pro binary')}  {self._tarball()}\n"
+        ).encode()
+        sig = _sign(priv, manifest)
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download.httpx.get", side_effect=self._mock_fetch(manifest, sig)):
+            with pytest.raises(RuntimeError, match="Version mismatch"):
+                _verify_pro_download(archive, self.PRO_VERSION)
+
+    def test_tampered_manifest_fails_signature(self, tmp_path):
+        """A manifest tampered after signing fails the signature gate (not the hash)."""
+        priv, pub_b64 = _make_key()
+        archive = tmp_path / "binary"
+        archive.write_bytes(b"the real pro binary")
+        manifest = (
+            f"version={self.PRO_VERSION}\n"
+            f"{self._hash(b'the real pro binary')}  {self._tarball()}\n"
+        ).encode()
+        sig = _sign(priv, manifest)
+        tampered = manifest.replace(self._tarball().encode(), b"evil.tar.gz")
+        with patch("cloakbrowser.download.BINARY_SIGNING_PUBKEYS", [pub_b64]), \
+             patch("cloakbrowser.download.httpx.get", side_effect=self._mock_fetch(tampered, sig)):
+            with pytest.raises(RuntimeError, match="signature verification failed"):
+                _verify_pro_download(archive, self.PRO_VERSION)
+
+
+class TestProDownloadVersionPinned:
+    """The Pro download must request the explicit version, NOT /latest, so the
+    served artifact matches the version-pinned signed manifest it's verified
+    against (no latest-advances TOCTOU)."""
+
+    def test_download_url_is_version_pinned(self):
+        from cloakbrowser.config import DOWNLOAD_BASE_URL
+
+        captured = {}
+
+        def fake_download_file(url, dest, headers=None):
+            captured["url"] = url
+
+        with patch("cloakbrowser.download._download_file", side_effect=fake_download_file), \
+             patch("cloakbrowser.download._verify_pro_download"), \
+             patch("cloakbrowser.download._extract_archive"):
+            _download_pro_binary("147.0.1.0", "cb_key")
+
+        assert captured["url"] == f"{DOWNLOAD_BASE_URL}/api/download/147.0.1.0"
+        assert not captured["url"].endswith("/latest")
+
+
+class TestVersionBinding:
+    """The 'version=<v>' line: read by new wrappers, ignored by old parsers."""
+
+    def test_parse_manifest_version(self):
+        manifest = "version=146.0.7680.177.5\nabc  cloakbrowser-linux-x64.tar.gz\n"
+        assert _parse_manifest_version(manifest) == "146.0.7680.177.5"
+
+    def test_parse_manifest_version_absent(self):
+        assert _parse_manifest_version("abc  cloakbrowser-linux-x64.tar.gz\n") is None
+
+    def test_old_checksum_parser_ignores_version_line(self):
+        """Regression: the version line must not pollute the old hash map."""
+        h = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+        manifest = f"version=146.0.7680.177.5\n{h}  cloakbrowser-linux-x64.tar.gz\n"
+        result = _parse_checksums(manifest)
+        assert result == {"cloakbrowser-linux-x64.tar.gz": h}
+
+
+class TestFetchSignedManifest:
+    """_fetch_signed_manifest pairs SHA256SUMS + .sig from the same origin."""
+
+    def test_fetches_both_from_primary(self):
+        def mock_get(url, **kwargs):
+            resp = MagicMock()
+            resp.raise_for_status = MagicMock()
+            resp.content = b"SIG" if url.endswith(".sig") else b"MANIFEST"
+            return resp
+
+        with patch("cloakbrowser.download.httpx.get", side_effect=mock_get):
+            result = _fetch_signed_manifest("1.2.3.4")
+        assert result == (b"MANIFEST", b"SIG")
+
+    def test_falls_back_to_github_when_primary_missing_sig(self):
+        def mock_get(url, **kwargs):
+            resp = MagicMock()
+            resp.content = b"SIG" if url.endswith(".sig") else b"MANIFEST"
+            if "cloakbrowser.dev" in url and url.endswith(".sig"):
+                resp.raise_for_status.side_effect = Exception("404")
+            else:
+                resp.raise_for_status = MagicMock()
+            return resp
+
+        with patch("cloakbrowser.download.httpx.get", side_effect=mock_get):
+            result = _fetch_signed_manifest("1.2.3.4")
+        assert result == (b"MANIFEST", b"SIG")
+
+    def test_returns_none_when_all_fail(self):
+        with patch("cloakbrowser.download.httpx.get", side_effect=Exception("network")):
+            assert _fetch_signed_manifest("1.2.3.4") is None