feat: native SOCKS5 proxy support in proxy= parameter

Route SOCKS5/SOCKS5h proxies via --proxy-server Chrome arg instead of
Playwright's proxy dict (which rejects SOCKS5 with credentials).
Handles string URLs, Playwright dicts, IPv6, bypass lists.

SOCKS5 geoip exit IP resolution uses socks-proxy-agent (optional peer
dep). Falls back to DNS if not installed.

js/src/geoip.ts

@@ -15,7 +15,7 @@ import dns from "node:dns/promises";
 import net from "node:net";
 import { getCacheDir } from "./config.js";
 import type { LaunchOptions } from "./types.js";
-import { ensureProxyScheme } from "./proxy.js";
+import { ensureProxyScheme, isSocksProxy, reconstructSocksUrl, type ProxyDict } from "./proxy.js";
 
 // P3TERX mirror of MaxMind GeoLite2-City — no license key needed
 const GEOIP_DB_URL =
@@ -129,9 +129,44 @@ const IP_ECHO_URLS = [
 ];
 
 async function resolveExitIp(proxyUrl: string): Promise<string | null> {
-  // Node.js fetch doesn't support proxy natively — use a CONNECT tunnel via http
-  // For simplicity, use a direct HTTP request to a plain-text IP echo service
-  // through the proxy using Node's http module
+  const isSocks = isSocksProxy(proxyUrl);
+
+  // SOCKS5: tunnel through the SOCKS5 proxy via socks-proxy-agent
+  if (isSocks) {
+    let SocksProxyAgent: typeof import("socks-proxy-agent").SocksProxyAgent;
+    try {
+      ({ SocksProxyAgent } = await import("socks-proxy-agent"));
+    } catch {
+      console.warn("[cloakbrowser] socks-proxy-agent not installed — cannot resolve exit IP through SOCKS5 proxy. Install it: npm install socks-proxy-agent");
+      return null;
+    }
+    const { default: https } = await import("node:https");
+    const agent = new SocksProxyAgent(proxyUrl);
+
+    for (const echoUrl of IP_ECHO_URLS) {
+      try {
+        const ip = await new Promise<string | null>((resolve) => {
+          const req = https.request(echoUrl, { agent, timeout: 10_000 }, (res) => {
+            let data = "";
+            res.on("data", (chunk: Buffer) => (data += chunk.toString()));
+            res.on("end", () => {
+              const ip = data.trim();
+              resolve(net.isIP(ip) ? ip : null);
+            });
+          });
+          req.on("error", () => resolve(null));
+          req.on("timeout", () => { req.destroy(); resolve(null); });
+          req.end();
+        });
+        if (ip) return ip;
+      } catch {
+        continue;
+      }
+    }
+    return null;
+  }
+
+  // HTTP/HTTPS: use a CONNECT tunnel via http
   try {
     const { default: http } = await import("node:http");
     const { default: https } = await import("node:https");
@@ -264,6 +299,22 @@ function maybeTriggerUpdate(dbPath: string): void {
   downloadGeoipDb(dbPath).catch(() => {});
 }
 
+/**
+ * Extract a usable proxy URL from LaunchOptions.proxy.
+ * For SOCKS5 dicts with separate credentials, reconstructs the full URL
+ * with inline credentials so SOCKS5 auth works.
+ */
+function extractProxyUrl(proxy: string | ProxyDict | undefined): string | null {
+  if (!proxy) return null;
+  if (typeof proxy === "string") return ensureProxyScheme(proxy);
+  const p = proxy as ProxyDict;
+  if (!p.server) return null;
+  if (p.username && isSocksProxy(p)) {
+    return reconstructSocksUrl(p);
+  }
+  return ensureProxyScheme(p.server);
+}
+
 /**
  * Auto-fill timezone/locale from proxy IP when geoip is enabled.
  * Also returns exitIp as a free bonus (reused for WebRTC spoofing).
@@ -273,9 +324,8 @@ export async function maybeResolveGeoip(
 ): Promise<{ timezone?: string; locale?: string; exitIp?: string }> {
   if (!options.geoip || !options.proxy) return { timezone: options.timezone, locale: options.locale };
 
-  let proxyUrl = typeof options.proxy === "string" ? options.proxy : options.proxy.server;
+  const proxyUrl = extractProxyUrl(options.proxy);
   if (!proxyUrl) return { timezone: options.timezone, locale: options.locale };
-  proxyUrl = ensureProxyScheme(proxyUrl);
 
   // When both tz/locale are explicit, still resolve exit IP for WebRTC
   if (options.timezone && options.locale) {
@@ -304,13 +354,13 @@ export async function resolveWebrtcArgs(
   const idx = args.findIndex(a => a === "--fingerprint-webrtc-ip=auto");
   if (idx === -1) return args;
 
-  let proxyUrl = typeof options.proxy === "string" ? options.proxy : options.proxy?.server;
+  const proxyUrl = extractProxyUrl(options.proxy);
   if (!proxyUrl) {
+    console.warn("[cloakbrowser] --fingerprint-webrtc-ip=auto requires a proxy; removing flag");
     const result = [...args];
     result.splice(idx, 1);
     return result;
   }
-  proxyUrl = ensureProxyScheme(proxyUrl);
 
   try {
     const ip = await resolveExitIp(proxyUrl);
@@ -318,10 +368,12 @@ export async function resolveWebrtcArgs(
     if (ip) {
       result[idx] = `--fingerprint-webrtc-ip=${ip}`;
     } else {
+      console.warn("[cloakbrowser] Could not resolve proxy exit IP for WebRTC spoofing; removing --fingerprint-webrtc-ip=auto");
       result.splice(idx, 1);
     }
     return result;
   } catch {
+    console.warn("[cloakbrowser] Failed to resolve proxy exit IP for WebRTC spoofing; removing --fingerprint-webrtc-ip=auto");
     const result = [...args];
     result.splice(idx, 1);
     return result;

js/src/playwright.ts

@@ -8,7 +8,7 @@ import type { LaunchOptions, LaunchContextOptions, LaunchPersistentContextOption
 import { DEFAULT_VIEWPORT, IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
-import { parseProxyUrl } from "./proxy.js";
+import { resolveProxyConfig } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
 
 /** @internal Accept both timezone and timezoneId — either works, no warning. Exported for testing. */
@@ -39,20 +39,19 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
 
   const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
   const { exitIp, ...resolved } = await maybeResolveGeoip(options);
+  const { proxyOption, proxyArgs } = resolveProxyConfig(options.proxy);
   let resolvedArgs = await resolveWebrtcArgs(options);
   if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
     resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
   }
-  const args = buildArgs({ ...options, ...resolved, args: resolvedArgs });
+  const args = buildArgs({ ...options, ...resolved, args: [...(resolvedArgs ?? []), ...proxyArgs] });
 
   const browser = await chromium.launch({
     executablePath: binaryPath,
     headless: options.headless ?? true,
     args,
     ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
-    ...(options.proxy
-      ? { proxy: typeof options.proxy === "string" ? parseProxyUrl(options.proxy) : options.proxy }
-      : {}),
+    ...(proxyOption ? { proxy: proxyOption } : {}),
     ...options.launchOptions,
   });
 
@@ -164,11 +163,12 @@ export async function launchPersistentContext(
 
   const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
   const { exitIp, ...resolved } = await maybeResolveGeoip(options);
+  const { proxyOption, proxyArgs } = resolveProxyConfig(options.proxy);
   let resolvedArgs = await resolveWebrtcArgs(options);
   if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
     resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
   }
-  const args = buildArgs({ ...options, ...resolved, args: resolvedArgs });
+  const args = buildArgs({ ...options, ...resolved, args: [...(resolvedArgs ?? []), ...proxyArgs] });
 
   // locale and timezone are set via binary flags (--lang, --fingerprint-timezone)
   // — NOT via Playwright context kwargs which use detectable CDP emulation.
@@ -177,9 +177,7 @@ export async function launchPersistentContext(
     headless: options.headless ?? true,
     args,
     ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
-    ...(options.proxy
-      ? { proxy: typeof options.proxy === "string" ? parseProxyUrl(options.proxy) : options.proxy }
-      : {}),
+    ...(proxyOption ? { proxy: proxyOption } : {}),
     ...(options.userAgent ? { userAgent: options.userAgent } : {}),
     viewport: options.viewport === undefined ? DEFAULT_VIEWPORT : options.viewport,
     ...(options.colorScheme ? { colorScheme: options.colorScheme } : {}),

js/src/proxy.ts

@@ -23,6 +23,65 @@ export function ensureProxyScheme(proxyUrl: string): string {
  * Also handles: no credentials, URL-encoded special chars, socks5://, missing port,
  * and bare proxy strings without a scheme (e.g. "user:pass@host:port" -> treated as http).
  */
+/** Proxy dict shape accepted by Playwright/Puppeteer wrappers. */
+export type ProxyDict = { server: string; bypass?: string; username?: string; password?: string };
+
+/** Result of resolveProxyConfig — either Playwright dict OR Chrome arg, never both. */
+export interface ProxyConfig {
+  /** Playwright proxy option (for HTTP proxies). */
+  proxyOption?: ParsedProxy;
+  /** Chrome CLI args (for SOCKS5 proxies, e.g. ["--proxy-server=socks5://..."]). */
+  proxyArgs: string[];
+}
+
+/**
+ * Check if a proxy uses the SOCKS5 protocol.
+ */
+export function isSocksProxy(proxy: string | ProxyDict | undefined | null): boolean {
+  if (!proxy) return false;
+  const url = typeof proxy === "string" ? proxy : proxy.server;
+  return /^socks5h?:\/\//i.test(url);
+}
+
+/**
+ * Reconstruct a SOCKS5 URL with inline credentials from a proxy dict.
+ */
+export function reconstructSocksUrl(proxy: ProxyDict): string {
+  const url = new URL(proxy.server);
+  if (proxy.username) {
+    url.username = encodeURIComponent(proxy.username);
+    if (proxy.password) url.password = encodeURIComponent(proxy.password);
+  }
+  return url.href.replace(/\/$/, "");
+}
+
+/**
+ * Resolve proxy into Playwright option and/or Chrome args.
+ *
+ * Playwright rejects SOCKS5 proxies with credentials in its proxy dict,
+ * so SOCKS5 is passed via --proxy-server Chrome arg instead.
+ */
+export function resolveProxyConfig(proxy: string | ProxyDict | undefined): ProxyConfig {
+  if (!proxy) return { proxyArgs: [] };
+
+  if (isSocksProxy(proxy)) {
+    // SOCKS5: bypass Playwright, pass directly to Chrome via --proxy-server.
+    if (typeof proxy === "string") {
+      return { proxyArgs: [`--proxy-server=${proxy}`] };
+    }
+    const socksUrl = reconstructSocksUrl(proxy);
+    const args = [`--proxy-server=${socksUrl}`];
+    if (proxy.bypass) args.push(`--proxy-bypass-list=${proxy.bypass}`);
+    return { proxyArgs: args };
+  }
+
+  // HTTP/HTTPS: use Playwright's proxy dict
+  if (typeof proxy === "string") {
+    return { proxyOption: parseProxyUrl(proxy), proxyArgs: [] };
+  }
+  return { proxyOption: proxy as ParsedProxy, proxyArgs: [] };
+}
+
 export function parseProxyUrl(proxy: string): ParsedProxy {
   let url: URL;
   // Bare format: "user:pass@host:port" — new URL() throws without a scheme.

js/src/puppeteer.ts

@@ -9,7 +9,7 @@ import type { LaunchOptions } from "./types.js";
 import { IGNORE_DEFAULT_ARGS } from "./config.js";
 import { buildArgs } from "./args.js";
 import { ensureBinary } from "./download.js";
-import { parseProxyUrl } from "./proxy.js";
+import { isSocksProxy, parseProxyUrl, resolveProxyConfig } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";
 
 /**
@@ -39,25 +39,27 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
   const args = buildArgs({ ...options, ...resolved, args: resolvedArgs });
 
   // Puppeteer handles proxy via CLI args, not a separate option.
-  // Chromium's --proxy-server does NOT support inline credentials,
-  // so we strip them and use page.authenticate() instead.
+  // SOCKS5: Chrome supports inline credentials natively (RFC 1929 auth).
+  // HTTP: Chrome does NOT support inline credentials — strip them and
+  // use page.authenticate() for Proxy-Authorization headers instead.
   let proxyAuth: { username: string; password: string } | undefined;
   if (options.proxy) {
-    if (typeof options.proxy === "string") {
+    if (isSocksProxy(options.proxy)) {
+      // SOCKS5: pass full URL with credentials to Chrome directly
+      const { proxyArgs } = resolveProxyConfig(options.proxy);
+      args.push(...proxyArgs);
+    } else if (typeof options.proxy === "string") {
       const { server, username, password } = parseProxyUrl(options.proxy);
       args.push(`--proxy-server=${server}`);
       if (username) {
         proxyAuth = { username, password: password ?? "" };
       }
     } else {
-      // Strip any inline credentials from the server URL — Chromium's
-      // --proxy-server doesn't support them; use page.authenticate() instead.
       const parsed = parseProxyUrl(options.proxy.server);
       args.push(`--proxy-server=${parsed.server}`);
       if (options.proxy.bypass) {
         args.push(`--proxy-bypass-list=${options.proxy.bypass}`);
       }
-      // Explicit username/password fields take precedence over inline creds
       const username = options.proxy.username ?? parsed.username;
       const password = options.proxy.password ?? parsed.password;
       if (username) {