Fix authenticated HTTP proxies across all platforms

Route authenticated HTTP/HTTPS proxies through the browser's native proxy
authentication only on binaries that support it, resolved per platform and
binary version via a capability gate (sibling to the existing viewport and
window-geometry gates). Older binaries, including the free macOS and ARM
builds, fall back to the standard Playwright proxy path instead of emitting
credentials the binary cannot parse, so authenticated proxies keep working on
macOS and ARM instead of silently failing. Applied across the Python,
JavaScript, Puppeteer, and .NET wrappers.

Author: Cloak-HQ

CHANGELOG.md

@@ -8,6 +8,8 @@ Changes are tagged: **[wrapper]** for Python/JS wrapper, **[binary]** for Chromi
 
 ## [Unreleased]
 
+- **[wrapper]** Authenticated HTTP/HTTPS proxies now use the browser's native proxy authentication on every platform whose binary supports it — resolved per platform and binary version — and fall back to the standard proxy path on older binaries that don't. Fixes credentialed HTTP/HTTPS proxies on macOS and ARM, which previously could not use the native path. Python, JavaScript, Puppeteer, and .NET.
+
 ## [0.4.10] — 2026-07-09
 
 - **[wrapper]** Fix JS CLI silently exiting with no output when run via `npx`/`node_modules/.bin` (#427). The entry-point guard compared `import.meta.url` to an unresolved `process.argv[1]`; symlinked bin installs (npm/pnpm/npx) never matched, so no subcommand ran. Now realpath-resolves the invoked path before comparing.

cloakbrowser/browser.py

@@ -24,9 +24,9 @@
     DEFAULT_VIEWPORT,
     IGNORE_DEFAULT_ARGS,
     binary_supports_headless_no_viewport,
+    binary_supports_http_proxy_inline_auth,
     binary_supports_maximized_window,
     get_default_stealth_args,
-    normalize_requested_version,
 )
 from .download import ensure_binary
 from .license import build_launch_env
@@ -206,7 +206,7 @@ def launch(
 
     binary_path = ensure_binary(license_key=license_key, browser_version=browser_version)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version)
+    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version, license_key)
     args = _resolve_webrtc_args(args, proxy)
     args = _append_webrtc_exit_ip(args, exit_ip)
 
@@ -312,7 +312,7 @@ async def launch_async(  # noqa: C901
 
     binary_path = ensure_binary(license_key=license_key, browser_version=browser_version)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version)
+    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version, license_key)
     args = _resolve_webrtc_args(args, proxy)
     args = _append_webrtc_exit_ip(args, exit_ip)
     chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths, start_maximized=binary_supports_maximized_window(license_key, browser_version) and not _suppress_maximize)
@@ -428,7 +428,7 @@ def launch_persistent_context(
 
     binary_path = ensure_binary(license_key=license_key, browser_version=browser_version)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version)
+    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version, license_key)
     args = _resolve_webrtc_args(args, proxy)
     args = _append_webrtc_exit_ip(args, exit_ip)
     chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths, start_maximized=binary_supports_maximized_window(license_key, browser_version) and viewport is _VIEWPORT_UNSET and "viewport" not in kwargs and "no_viewport" not in kwargs)
@@ -565,7 +565,7 @@ async def launch_persistent_context_async(
 
     binary_path = ensure_binary(license_key=license_key, browser_version=browser_version)
     timezone, locale, exit_ip = maybe_resolve_geoip(geoip, proxy, timezone, locale)
-    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version)
+    proxy_kwargs, proxy_extra_args = _resolve_proxy_config(proxy, browser_version, license_key)
     args = _resolve_webrtc_args(args, proxy)
     args = _append_webrtc_exit_ip(args, exit_ip)
     chrome_args = build_args(stealth_args, (args or []) + proxy_extra_args, timezone=timezone, locale=locale, headless=headless, extension_paths=extension_paths, start_maximized=binary_supports_maximized_window(license_key, browser_version) and viewport is _VIEWPORT_UNSET and "viewport" not in kwargs and "no_viewport" not in kwargs)
@@ -1379,26 +1379,6 @@ def _normalize_http_string_url(url: str) -> str:
     return result
 
 
-_HTTP_PROXY_INLINE_AUTH_MIN_VERSION = "146.0.7680.177.5"
-_HTTP_PROXY_INLINE_AUTH_PLATFORMS = {"linux-x64", "windows-x64"}
-
-
-def _supports_http_proxy_inline_auth(version: str | None = None) -> bool:
-    """Check if the running binary supports HTTP proxy inline credentials.
-
-    Requires both a supported platform AND a binary version with preemptive proxy
-    auth. ``version`` is the pinned/resolved Chromium version actually being
-    launched; when None it falls back to the platform default. Passing the pin
-    matters because a rollback can run a binary older than the default (#182).
-    """
-    from .config import get_platform_tag, get_chromium_version, _version_tuple
-    tag = get_platform_tag()
-    if tag not in _HTTP_PROXY_INLINE_AUTH_PLATFORMS:
-        return False
-    effective = version or get_chromium_version()
-    return _version_tuple(effective) >= _version_tuple(_HTTP_PROXY_INLINE_AUTH_MIN_VERSION)
-
-
 def _is_socks_proxy(proxy: str | ProxySettings | None) -> bool:
     """Check if the proxy uses SOCKS5 protocol."""
     if proxy is None:
@@ -1410,12 +1390,15 @@ def _is_socks_proxy(proxy: str | ProxySettings | None) -> bool:
 def _resolve_proxy_config(
     proxy: str | ProxySettings | None,
     browser_version: str | None = None,
+    license_key: str | None = None,
 ) -> tuple[dict[str, Any], list[str]]:
     """Resolve proxy into Playwright kwargs and Chrome args.
 
-    Proxies with credentials (SOCKS5 or HTTP/HTTPS) are passed via Chrome's
-    --proxy-server flag with inline credentials, bypassing Playwright's CDP
-    auth interceptor which breaks on some proxies and Google domains (#182).
+    Proxies with credentials (SOCKS5 always; HTTP/HTTPS only on binaries that
+    support inline proxy auth) are passed via Chrome's --proxy-server flag with
+    inline credentials, bypassing Playwright's CDP auth interceptor which breaks
+    on some proxies and Google domains (#182). HTTP/HTTPS creds on older binaries
+    fall back to Playwright's proxy dict.
 
     Returns:
         (proxy_kwargs, extra_chrome_args) — one or both will be empty.
@@ -1436,11 +1419,13 @@ def _resolve_proxy_config(
         # passwords at '=' and other special chars (#157).
         return {}, [f"--proxy-server={_normalize_socks_string_url(proxy)}"]
 
-    # HTTP/HTTPS with credentials on supported platforms: use Chrome's native
-    # proxy authentication path instead of Playwright's CDP auth interceptor
-    # (#182).
-    requested_version = normalize_requested_version(browser_version)
-    if _has_credentials(proxy) and _supports_http_proxy_inline_auth(requested_version):
+    # HTTP/HTTPS with credentials, only on binaries that ship inline proxy auth:
+    # use Chrome's native proxy authentication path instead of Playwright's CDP
+    # auth interceptor (#182). Older binaries (free macOS/linux-arm64) can't parse
+    # inline credentials, so they fall through to the Playwright proxy dict below.
+    if _has_credentials(proxy) and binary_supports_http_proxy_inline_auth(
+        license_key, browser_version
+    ):
         if isinstance(proxy, dict):
             url = _reconstruct_http_url(proxy)
             extra_args = [f"--proxy-server={url}"]

cloakbrowser/config.py

@@ -344,6 +344,70 @@ def binary_supports_headless_no_viewport(
         return False
 
 
+# ---------------------------------------------------------------------------
+# Inline HTTP proxy authentication by binary version
+# ---------------------------------------------------------------------------
+# First Chromium build, per platform, whose binary can take inline HTTP proxy
+# credentials (Chromium-native ``--proxy-server=http://user:pass@host``). Below
+# the floor the wrapper MUST route credentialed HTTP/HTTPS proxies through
+# Playwright's proxy dict instead — an older binary treats the ``user:pass@``
+# authority as an invalid proxy host and drops proxy auth (#182).
+#
+# A single global threshold (like HEADLESS_NO_VIEWPORT_MIN_VERSION) can't model
+# this: the capability landed in different build lineages at different points —
+# linux-x64/windows-x64 have it at 146.0.7680.177.5, but the free macOS (145.x)
+# and linux-arm64 (146.0.7680.177.3) floors predate it, so those only qualify
+# once they resolve to a Pro/newer build (148+). Platforms absent from this map
+# are treated as never-inline (unknown capability => safe fallback).
+HTTP_PROXY_INLINE_AUTH_MIN_VERSION: dict[str, str] = {
+    "linux-x64": "146.0.7680.177.5",
+    "windows-x64": "146.0.7680.177.5",
+    "linux-arm64": "148.0.7778.215.3",
+    "darwin-arm64": "148.0.7778.215.3",
+    "darwin-x64": "148.0.7778.215.3",
+}
+
+
+def binary_supports_http_proxy_inline_auth(
+    license_key: str | None = None, browser_version: str | None = None
+) -> bool:
+    """Whether the resolved binary accepts inline HTTP proxy credentials.
+
+    The capability is a function of the binary version; ``license_key`` only
+    resolves *which* version launches (Pro build vs free default), exactly like
+    ``binary_supports_headless_no_viewport``. A declared pin wins, else a valid
+    Pro license resolves to the Pro build (which ships the patch), else the free
+    per-platform default — then it compares to this platform's floor. Below the
+    floor, credentialed HTTP proxies fall back to Playwright's proxy dict. A
+    local override with no declared version is unknown-version, so stay on the
+    safe fallback. Python, JS and .NET mirror this gate.
+    """
+    floor = HTTP_PROXY_INLINE_AUTH_MIN_VERSION.get(get_platform_tag())
+    if floor is None:
+        return False
+    try:
+        declared = normalize_requested_version(browser_version)
+    except ValueError:
+        declared = None
+    if declared:
+        version = declared
+    elif get_local_binary_override():
+        return False
+    else:
+        from .license import resolve_license_key
+
+        pro = bool(resolve_license_key(license_key))
+        version = get_effective_version(pro=pro)
+    if version is None:
+        # Pro with no cached marker => resolve latest Pro from the server, which
+        # is >= the floor by construction and always ships the patch.
+        return True
+    try:
+        return not _version_newer(floor, version)
+    except (ValueError, AttributeError):
+        return False
+
+
 def binary_supports_maximized_window(
     license_key: str | None = None, browser_version: str | None = None
 ) -> bool:

dotnet/src/CloakBrowser/CloakLauncher.cs

@@ -26,7 +26,7 @@ public static async Task<CloakBrowserHandle> LaunchAsync(LaunchOptions? options
         string binaryPath = await Download.EnsureBinaryAsync(options.LicenseKey, options.BrowserVersion).ConfigureAwait(false);
         var (timezone, locale, exitIp) = await MaybeResolveGeoIpAsync(
             options.GeoIp, options.Proxy, options.Timezone, options.Locale).ConfigureAwait(false);
-        var proxyResolution = ProxyResolver.Resolve(options.Proxy, options.BrowserVersion);
+        var proxyResolution = ProxyResolver.Resolve(options.Proxy, options.BrowserVersion, options.LicenseKey);
         var args = await ResolveWebRtcArgsAsync(options.Args, options.Proxy).ConfigureAwait(false);
         args = MaybeAppendWebRtcExitIp(args, exitIp);
 
@@ -136,7 +136,7 @@ public static async Task<CloakContextHandle> LaunchPersistentContextAsync(
         string binaryPath = await Download.EnsureBinaryAsync(options.LicenseKey, options.BrowserVersion).ConfigureAwait(false);
         var (timezone, locale, exitIp) = await MaybeResolveGeoIpAsync(
             options.GeoIp, options.Proxy, options.Timezone, options.Locale).ConfigureAwait(false);
-        var proxyResolution = ProxyResolver.Resolve(options.Proxy, options.BrowserVersion);
+        var proxyResolution = ProxyResolver.Resolve(options.Proxy, options.BrowserVersion, options.LicenseKey);
         var args = await ResolveWebRtcArgsAsync(options.Args, options.Proxy).ConfigureAwait(false);
         args = MaybeAppendWebRtcExitIp(args, exitIp);
 

dotnet/src/CloakBrowser/Config.cs

@@ -452,4 +452,81 @@ public static bool BinarySupportsHeadlessNoViewport(string? licenseKey = null, s
     /// </summary>
     public static bool BinarySupportsMaximizedWindow(string? licenseKey = null, string? browserVersion = null)
         => BinarySupportsHeadlessNoViewport(licenseKey, browserVersion);
+
+    // First Chromium build, per platform, whose binary can take inline HTTP proxy
+    // credentials (Chromium-native --proxy-server=http://user:pass@host). Below the
+    // floor the wrapper MUST route credentialed HTTP/HTTPS proxies through
+    // Playwright's proxy object — an older binary treats the user:pass@ authority as
+    // an invalid proxy host and drops proxy auth (#182). A single global threshold
+    // can't model this: the capability landed in different build lineages at different
+    // points (linux-x64/windows-x64 at 146.0.7680.177.5, but the free macOS 145.x and
+    // linux-arm64 146.0.7680.177.3 floors predate it, qualifying only once they resolve
+    // to a Pro/newer 148+ build). Platforms absent from this map are never-inline.
+    public static readonly IReadOnlyDictionary<string, string> HttpProxyInlineAuthMinVersion =
+        new Dictionary<string, string>
+        {
+            ["linux-x64"] = "146.0.7680.177.5",
+            ["windows-x64"] = "146.0.7680.177.5",
+            ["linux-arm64"] = "148.0.7778.215.3",
+            ["darwin-arm64"] = "148.0.7778.215.3",
+            ["darwin-x64"] = "148.0.7778.215.3",
+        };
+
+    /// <summary>
+    /// Whether the resolved binary accepts inline HTTP proxy credentials. The
+    /// capability is a function of the binary version; <paramref name="licenseKey"/>
+    /// only resolves which version launches (Pro build vs free default), exactly like
+    /// <see cref="BinarySupportsHeadlessNoViewport"/>. A declared pin wins, else a valid
+    /// Pro license resolves to the Pro build (which ships the patch), else the free
+    /// per-platform default — then it compares to this platform's floor. Below the
+    /// floor, credentialed HTTP proxies fall back to Playwright's proxy object. A local
+    /// override with no declared version is unknown-version, so stay on the safe
+    /// fallback. Python, JS and .NET mirror this gate.
+    /// </summary>
+    public static bool BinarySupportsHttpProxyInlineAuth(string? licenseKey = null, string? browserVersion = null)
+    {
+        string tag;
+        try
+        {
+            tag = GetPlatformTag();
+        }
+        catch
+        {
+            return false;
+        }
+        if (!HttpProxyInlineAuthMinVersion.TryGetValue(tag, out var floor))
+            return false;
+        string? declared;
+        try
+        {
+            declared = NormalizeRequestedVersion(browserVersion);
+        }
+        catch
+        {
+            declared = null;
+        }
+        string? version;
+        if (!string.IsNullOrEmpty(declared))
+        {
+            version = declared!;
+        }
+        else if (GetLocalBinaryOverride() != null)
+        {
+            return false;
+        }
+        else
+        {
+            bool pro = !string.IsNullOrEmpty(License.ResolveLicenseKey(licenseKey));
+            version = GetEffectiveVersion(pro);
+        }
+        if (version == null) return false;
+        try
+        {
+            return !VersionNewer(floor, version);
+        }
+        catch
+        {
+            return false;
+        }
+    }
 }

dotnet/src/CloakBrowser/ProxyResolver.cs

@@ -7,10 +7,6 @@ namespace CloakBrowser;
 /// </summary>
 internal static class ProxyResolver
 {
-    private const string HttpProxyInlineAuthMinVersion = "146.0.7680.177.5";
-    private static readonly IReadOnlySet<string> HttpProxyInlineAuthPlatforms =
-        new HashSet<string> { "linux-x64", "windows-x64" };
-
     /// <summary>Result of resolving a proxy: Playwright proxy (or null) plus extra Chrome args.</summary>
     public sealed record ProxyResolution(Microsoft.Playwright.Proxy? PlaywrightProxy, List<string> ExtraArgs);
 
@@ -267,28 +263,6 @@ private static Microsoft.Playwright.Proxy ParseProxyUrl(string proxy)
         return result;
     }
 
-    private static bool SupportsHttpProxyInlineAuth(string? version = null)
-    {
-        string tag = Config.GetPlatformTag();
-        if (!HttpProxyInlineAuthPlatforms.Contains(tag))
-            return false;
-        return Compare(version ?? Config.GetChromiumVersion(), HttpProxyInlineAuthMinVersion) >= 0;
-    }
-
-    private static int Compare(string a, string b)
-    {
-        var ta = Config.VersionTuple(a);
-        var tb = Config.VersionTuple(b);
-        int n = Math.Max(ta.Length, tb.Length);
-        for (int i = 0; i < n; i++)
-        {
-            int va = i < ta.Length ? ta[i] : 0;
-            int vb = i < tb.Length ? tb[i] : 0;
-            if (va != vb) return va.CompareTo(vb);
-        }
-        return 0;
-    }
-
     /// <summary>Extract a normalized proxy URL string from a string or dict proxy (for geoip / webrtc).</summary>
     public static string? ExtractProxyUrl(object? proxy)
     {
@@ -307,7 +281,7 @@ private static int Compare(string a, string b)
     }
 
     /// <summary>Resolve a proxy into Playwright options + extra Chrome args (one or both empty).</summary>
-    public static ProxyResolution Resolve(object? proxy, string? browserVersion = null)
+    public static ProxyResolution Resolve(object? proxy, string? browserVersion = null, string? licenseKey = null)
     {
         if (proxy == null)
             return new ProxyResolution(null, new List<string>());
@@ -333,15 +307,16 @@ public static ProxyResolution Resolve(object? proxy, string? browserVersion = nu
             return new ProxyResolution(null, new List<string> { $"--proxy-server={NormalizeSocksStringUrl(sUrl)}" });
         }
 
-        // HTTP/HTTPS with credentials on supported platforms: inline creds via --proxy-server.
+        // HTTP/HTTPS with credentials, only on binaries that ship inline proxy auth:
+        // inline creds via --proxy-server. Older binaries (free macOS/linux-arm64)
+        // can't parse inline credentials, so they fall through to Playwright's proxy.
         bool hasCreds = proxy switch
         {
             ProxySettings ps => HasCredentials(ps),
             string s => HasCredentials(s),
             _ => false,
         };
-        var requestedVersion = Config.NormalizeRequestedVersion(browserVersion);
-        if (hasCreds && SupportsHttpProxyInlineAuth(requestedVersion))
+        if (hasCreds && Config.BinarySupportsHttpProxyInlineAuth(licenseKey, browserVersion))
         {
             if (proxy is ProxySettings psd)
             {