chore(deps): bump actions/checkout in the actions group

Bumps the actions group with 1 update: [actions/checkout](https://github.com/actions/checkout).


Updates `actions/checkout` from 6.0.3 to 7.0.0
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/df4cb1c069e1874edd31b4311f1884172cec0e10...9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: 7.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>

.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

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
   python:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.12"
@@ -22,7 +22,7 @@ jobs:
   javascript:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
         with:
           node-version: 20

.github/workflows/publish.yml

@@ -24,7 +24,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.12"
@@ -42,7 +42,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.12"
@@ -62,7 +62,7 @@ jobs:
     permissions:
       id-token: write  # OIDC trusted publishing — no PYPI_TOKEN needed
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.12"
@@ -80,7 +80,7 @@ jobs:
     permissions:
       id-token: write  # OIDC trusted publishing + provenance — no NPM_TOKEN needed
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
         with:
           node-version: 24  # npm 11.11.0 native — no upgrade needed (Node 22.22.2 has broken npm)
@@ -100,7 +100,7 @@ jobs:
       attestations: write
       packages: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
       - name: Extract version
         run: |
           VERSION=$(python -c 'import re; print(re.search(r"__version__\s*=\s*[\"'\'']([^\"'\'']+)", open("cloakbrowser/_version.py").read()).group(1))')

.gitignore

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

CHANGELOG.md

@@ -8,6 +8,10 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi
 
 ## [Unreleased]
 
+- **[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.
+
 ## [0.3.32] — 2026-06-20
 
 - **[wrapper]** **Security**: Windows binary extraction — pass archive/destination paths to PowerShell via env vars instead of interpolating into the `-Command` string, closing a code-injection shape on paths containing single quotes (e.g. `C:\Users\O'Brien`)

README.md

@@ -254,7 +254,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
 
@@ -621,7 +621,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 |
@@ -1240,7 +1240,6 @@ 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
@@ -1289,7 +1288,7 @@ A: Yes. Pass `proxy="http://user:pass@host:port"` or `proxy="socks5://user:pass@
 
 ## 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)

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,7 +143,6 @@ 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,
@@ -86,10 +167,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,7 +183,9 @@ def launch(
         >>> print(page.title())
         >>> browser.close()
     """
-    sync_playwright = _import_sync_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.sync_api import sync_playwright
 
     binary_path = ensure_binary()
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
@@ -115,7 +194,7 @@ def launch(
     if exit_ip and not (args and any(a.startswith("--fingerprint-webrtc-ip") for a in args)):
         args = list(args or [])
         args.append(f"--fingerprint-webrtc-ip={exit_ip}")
-        
+
     chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths)
 
     logger.debug("Launching stealth Chromium (headless=%s, args=%d)", headless, len(chrome_args))
@@ -141,6 +220,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,7 +244,6 @@ 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,
@@ -177,7 +261,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,7 +282,9 @@ async def launch_async(  # noqa: C901
         >>>
         >>> asyncio.run(main())
     """
-    async_playwright = _import_async_playwright(_resolve_backend(backend))
+    _check_removed_kwargs(kwargs)
+
+    from playwright.async_api import async_playwright
 
     binary_path = ensure_binary()
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
@@ -233,6 +318,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,7 +344,6 @@ 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,
@@ -286,7 +374,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,7 +390,9 @@ 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)
 
@@ -327,15 +416,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.update(_resolve_context_viewport(viewport, headless))
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
     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,7 +468,6 @@ 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,
@@ -411,7 +495,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,7 +516,9 @@ 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)
 
@@ -457,15 +542,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.update(_resolve_context_viewport(viewport, headless))
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
     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,7 +593,6 @@ 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,
@@ -538,7 +618,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 +626,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 +641,16 @@ 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)
 
     context_kwargs: dict[str, Any] = {}
     if user_agent:
         context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
     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,7 +690,6 @@ 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,
@@ -640,7 +716,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 +743,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 +757,16 @@ 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)
 
     context_kwargs: dict[str, Any] = {}
     if user_agent:
         context_kwargs["user_agent"] = user_agent
-    if viewport is _VIEWPORT_UNSET:
+    context_kwargs.update(_resolve_context_viewport(viewport, headless))
-        context_kwargs["viewport"] = DEFAULT_VIEWPORT
-    elif viewport is None:
-        context_kwargs["no_viewport"] = True
-    else:
-        context_kwargs["viewport"] = viewport
     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 +801,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
+    # Linux/Windows: Windows fingerprint profile.
-    # Hardware concurrency, device memory, screen, window size, and GPU are
+    # Screen and window size come from the real display, not this flag (verified:
-    # auto-generated by the binary from the seed (v14+).
+    # 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
+# Default viewport — used for HEADLESS only (headed launches use no_viewport so
-# screen=1920x1080, availHeight=1032 (minus 48px taskbar, binary default),
+# the page tracks the real window). Headless has no window chrome, so a fixed
-# innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks)
+# 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}
 

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,
@@ -162,9 +163,11 @@ def _download_and_extract(version: str | None = None) -> None:
             )
             _download_file(fallback_url, tmp_path)
 
-        # Verify checksum before extraction
+        # Verify the download before extraction. On the official path this is a
-        if os.environ.get("CLOAKBROWSER_SKIP_CHECKSUM", "").lower() != "true":
+        # mandatory, non-bypassable Ed25519 signature check (see
-            _verify_download_checksum(tmp_path, version)
+        # _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)
         _show_welcome()
@@ -174,22 +177,159 @@ def _download_and_extract(version: str | None = None) -> None:
 
 
 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."""
+    """Verify the downloaded archive's integrity and authenticity.
-    checksums = _fetch_checksums(version)
+
+    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 checksums is None:
+    if os.environ.get("CLOAKBROWSER_DOWNLOAD_URL"):
-        logger.warning("SHA256SUMS not available for this release — skipping checksum verification")
+        # 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 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
+            )
+            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:
-        logger.warning("SHA256SUMS found but no entry for %s — skipping verification", tarball_name)
+        raise RuntimeError(
-        return
+            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 +351,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()
+        parts = line.strip().split(None, 1)
-        if not line:
+        if len(parts) != 2:
             continue
-        parts = line.split(None, 1)
+        hash_val, filename = parts
-        if len(parts) == 2:
+        hash_val = hash_val.lower()
-            hash_val, filename = parts
+        if len(hash_val) != 64 or any(c not in "0123456789abcdef" for c in hash_val):
-            filename = filename.lstrip("*")
+            continue
-            result[filename] = hash_val.lower()
+        result[filename.lstrip("*")] = hash_val
     return result
 
 

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
 // ---------------------------------------------------------------------------
@@ -200,9 +213,11 @@ export const IGNORE_DEFAULT_ARGS = ["--enable-automation", "--enable-unsafe-swif
 // ---------------------------------------------------------------------------
 // Default stealth arguments
 // ---------------------------------------------------------------------------
-// Default viewport — realistic maximized Chrome on 1080p Windows
+// Default viewport — used for HEADLESS only (headed launches use no viewport so
-// screen=1920x1080, availHeight=1032 (minus 48px taskbar, binary default),
+// the page tracks the real window). Headless has no window chrome, so a fixed
-// innerHeight=947 (minus ~85px Chrome UI: tabs + address bar + bookmarks)
+// 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 +234,9 @@ export function getDefaultStealthArgs(): string[] {
     return [...base, "--fingerprint-platform=macos"];
   }
 
-  // Linux/Windows: spoof as Windows desktop
+  // Linux/Windows: spoof as Windows desktop.
-  // Hardware concurrency, device memory, screen, window size, and GPU are
+  // Screen and window size come from the real display, not this flag (verified:
-  // auto-generated by the binary from the seed (v14+).
+  // 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,7 @@ import { extract as tarExtract } from "tar";
 
 import type { BinaryInfo } from "./types.js";
 import {
+  BINARY_SIGNING_PUBKEYS,
   DOWNLOAD_BASE_URL,
   GITHUB_API_URL,
   GITHUB_DOWNLOAD_BASE_URL,
@@ -195,10 +196,11 @@ async function downloadAndExtract(version?: string): Promise<void> {
       await downloadFile(fallbackUrl, tmpPath);
     }
 
-    // Verify checksum before extraction
+    // Verify the download before extraction. On the official path this is a
-    if (process.env.CLOAKBROWSER_SKIP_CHECKSUM?.toLowerCase() !== "true") {
+    // mandatory, non-bypassable Ed25519 signature check (see
-      await verifyDownloadChecksum(tmpPath, version);
+    // 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 +212,176 @@ async function downloadAndExtract(version?: string): Promise<void> {
   }
 }
 
-async function verifyDownloadChecksum(filePath: string, version?: string): Promise<void> {
+/** @internal Exported for testing only. */
-  const checksums = await fetchChecksums(version);
+export async function verifyDownloadChecksum(filePath: string, version?: string): Promise<void> {
   const tarballName = getArchiveName();
 
-  if (!checksums) {
+  if (process.env.CLOAKBROWSER_DOWNLOAD_URL) {
-    console.warn("[cloakbrowser] SHA256SUMS not available for this release — skipping checksum verification");
+    // 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 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`);
+    throw new Error(
-    return;
+      `Signature-verified SHA256SUMS has no entry for ${tarballName} — ` +
+        `cannot confirm binary integrity.`
+    );
+  }
+  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)");
   }
 
-  await verifyChecksum(filePath, expected);
+  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. */

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;
 }
@@ -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 {

js/src/puppeteer.ts

@@ -6,13 +6,31 @@
 
 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());
@@ -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/tests/launch.test.ts

@@ -84,6 +84,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/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,234 @@
+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 {
+  fetchSignedManifest,
+  parseChecksums,
+  parseManifestVersion,
+  verifyDownloadChecksum,
+  verifySignature,
+} from "../src/download.js";
+import { 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("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")
+@patch("playwright.sync_api.sync_playwright")
-def test_extension_loading(mock_playwright_import, mock_ensure_binary):
+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_sync_playwright.return_value.start.return_value = mock_pw
-    mock_pw_manager.return_value.start.return_value = mock_pw
-
-    mock_playwright_import.return_value = mock_pw_manager
 
     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_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
+        Uses context-level proxy to avoid launching a separate browser
-        against regression if/when the upstream fix lands. Uses context-level
+        (event loop conflict).
-        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,
@@ -22,10 +24,14 @@ from cloakbrowser.download import (
     _check_wrapper_update,
     _download_and_extract,
     _fetch_checksums,
+    _fetch_signed_manifest,
     _get_latest_chromium_version,
     _parse_checksums,
+    _parse_manifest_version,
     _should_check_for_update,
     _verify_checksum,
+    _verify_download_checksum,
+    _verify_signature,
     _write_version_marker,
     check_for_update,
     clear_cache,
@@ -486,7 +492,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 +502,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 +556,232 @@ 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 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