@webhands/core 0.4.0 → 0.5.0

package/README.md

@@ -88,8 +88,10 @@ deliberately local and single-session by design.
   does NOT bypass authentication or solve CAPTCHAs programmatically, and it is not
   intended to.
 - **No fingerprint-spoofing / anti-detect tricks.** It leans on being a *real*
-  browser/profile/IP rather than spoofing. There is no proxy rotation or
-  anti-detect build here.
+  browser/profile/IP rather than spoofing. There is no proxy *rotation* or
+  anti-detect build here. (A single, user-chosen SOCKS proxy for traffic/DNS
+  control is available opt-in via `--proxy`; see *Optional: route traffic and
+  DNS through a SOCKS proxy* below.)
 - **Your own session only.** A replayed/stolen cookie does not work anyway
   (clearance is bound to the browser fingerprint and IP, not just the cookie);
   the design assumes the session is genuinely yours.
@@ -174,6 +176,51 @@ reputation still matter. The realistic recipe is stealth +
 IP (see
 [`docs/adr/0002`](docs/adr/0002-real-session-over-fingerprint-spoofing.md)).
 
+## Optional: route traffic and DNS through a SOCKS proxy (opt-in, default OFF)
+
+By default webhands connects directly on your own machine and IP. If you want
+the browser to egress through a chosen SOCKS proxy (a VPN exit, an SSH/Tor SOCKS
+endpoint, a residential proxy), pass `--proxy <socks-url>` to `serve` (or
+`launch`). It routes **all** browser traffic AND DNS through that one proxy:
+
+```sh
+# socks5h:// tunnels DNS through the proxy too (no DNS leak):
+npx webhands serve --headed --proxy socks5h://127.0.0.1:1080
+
+# with credentials:
+npx webhands serve --proxy socks5h://user:pass@host:1080
+```
+
+- **`socks5h://` means no DNS leak.** webhands adds Chromium's
+  `--host-resolver-rules` catch-all so even side channels (the DNS prefetcher)
+  cannot leak a raw local DNS query; only the proxy's own host is resolved
+  locally. This is the recommended form.
+- **`socks5://` (or `socks://`) allows local DNS.** Use it when you deliberately
+  want split DNS. URL loads still resolve at the proxy, but Chromium may issue
+  some local DNS. Override either way with the programmatic `proxyNoLeak`
+  option.
+- **A malformed `--proxy` value fails loudly** with a typed `InvalidProxyError`
+  (it never silently launches unproxied, which would leak the traffic you asked
+  to tunnel).
+
+Programmatic equivalent:
+
+```ts
+import {PlaywrightLaunchTransport} from '@webhands/core';
+
+const transport = new PlaywrightLaunchTransport(
+  {}, // profile location
+  [], // extra hands
+  {proxy: 'socks5h://127.0.0.1:1080'}, // all traffic + DNS via the proxy, no leak
+);
+```
+
+**Honest caveat.** A proxy changes your IP and DNS path; it does **not** by
+itself defeat bot detection, and a proxy/VPN/datacenter IP often reads WORSE
+than a clean residential one. This is a deliberate, scoped opt-in deviation from
+the "own IP" default (see
+[`docs/adr/0009`](docs/adr/0009-opt-in-socks-proxy-all-traffic-and-dns.md)).
+
 ## Security note (the `serve` endpoint runs arbitrary code)
 
 The page verbs execute caller-supplied expressions: `eval` runs a JS expression

package/dist/errors.d.ts

@@ -15,7 +15,7 @@
  * has to re-derive paths.
  */
 /** The closed set of identifiable `core` error conditions. */
-export type ControllerErrorCode = 'missing-browser-binary' | 'missing-stealth-dependency' | 'missing-profile' | 'attach-not-chromium' | 'attach-no-context' | 'no-live-server' | 'session-already-active';
+export type ControllerErrorCode = 'missing-browser-binary' | 'missing-stealth-dependency' | 'invalid-proxy' | 'missing-profile' | 'attach-not-chromium' | 'attach-no-context' | 'no-live-server' | 'session-already-active';
 /**
  * Base class for every identifiable `core` error. Branch on {@link code}.
  *
@@ -68,6 +68,26 @@ export declare class MissingStealthDependencyError extends ControllerError {
         cause?: unknown;
     });
 }
+/**
+ * The `--proxy` value (a SOCKS URL) could not be parsed into a usable proxy
+ * config. webhands routes ALL traffic and DNS through one SOCKS proxy, so the
+ * value must be a `socks5://` or `socks5h://` URL with a host and port (an
+ * optional `user:pass@` is allowed). We refuse a malformed value LOUDLY with
+ * this typed condition rather than silently launching with no proxy (which
+ * would leak the very traffic the user asked to tunnel). The CLI maps the
+ * {@link code} to a fix message showing the expected URL shape.
+ *
+ * Mirrors {@link MissingStealthDependencyError}: a stable typed error whose
+ * brittle detection is confined to one spot (the proxy parser).
+ */
+export declare class InvalidProxyError extends ControllerError {
+    readonly code = "invalid-proxy";
+    /** The offending raw `--proxy` value, echoed back so the user can see it. */
+    readonly value: string;
+    constructor(value: string, message?: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * The named profile has not been set up yet: its dedicated profile directory
  * does not exist on disk. A profile is created by the headed `setup-profile`

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAC5B,wBAAwB,GACxB,4BAA4B,GAC5B,iBAAiB,GACjB,qBAAqB,GACrB,mBAAmB,GACnB,gBAAgB,GAChB,wBAAwB,CAAC;AAE5B;;;;;;GAMG;AACH,8BAAsB,eAAgB,SAAQ,KAAK;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAC5C,8EAA8E;IAC9E,QAAQ,CAAC,iBAAiB,EAAG,IAAI,CAAU;gBAE/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAMxD;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,eAAe;IAC7D,QAAQ,CAAC,IAAI,4BAA4B;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAA0D,EACnE,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,6BAA8B,SAAQ,eAAe;IACjE,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAG3B,UAAU,SAAe,EACzB,OAAO,GAAE,MAA+Q,EACxR,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACvD,QAAQ,CAAC,IAAI,qBAAqB;IAClC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAG3B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAA0F,EACnG,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAM5B;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,IAAI,yBAAyB;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAGxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAuJ,EAChK,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,eAAe;IACxD,QAAQ,CAAC,IAAI,uBAAuB;IACpC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGzB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAA+H,EACxI,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAK5B;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,eAAe;IACrD,QAAQ,CAAC,IAAI,oBAAoB;gBAGhC,OAAO,GAAE,MAAoF,EAC7F,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,eAAe;IAC7D,QAAQ,CAAC,IAAI,4BAA4B;gBAGxC,OAAO,GAAE,MAAmE,EAC5E,OAAO,CAAC,EAAE;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAC;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAO1E"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -69,6 +69,27 @@ export class MissingStealthDependencyError extends ControllerError {
         this.dependency = dependency;
     }
 }
+/**
+ * The `--proxy` value (a SOCKS URL) could not be parsed into a usable proxy
+ * config. webhands routes ALL traffic and DNS through one SOCKS proxy, so the
+ * value must be a `socks5://` or `socks5h://` URL with a host and port (an
+ * optional `user:pass@` is allowed). We refuse a malformed value LOUDLY with
+ * this typed condition rather than silently launching with no proxy (which
+ * would leak the very traffic the user asked to tunnel). The CLI maps the
+ * {@link code} to a fix message showing the expected URL shape.
+ *
+ * Mirrors {@link MissingStealthDependencyError}: a stable typed error whose
+ * brittle detection is confined to one spot (the proxy parser).
+ */
+export class InvalidProxyError extends ControllerError {
+    code = 'invalid-proxy';
+    /** The offending raw `--proxy` value, echoed back so the user can see it. */
+    value;
+    constructor(value, message = `Invalid --proxy value ${JSON.stringify(value)}. Expected a SOCKS URL like socks5h://host:1080 or socks5://user:pass@host:1080 (socks5h tunnels DNS too; both route all traffic through the proxy).`, options) {
+        super(message, options);
+        this.value = value;
+    }
+}
 /**
  * The named profile has not been set up yet: its dedicated profile directory
  * does not exist on disk. A profile is created by the headed `setup-profile`

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH;;;;;;GAMG;AACH,MAAM,OAAgB,eAAgB,SAAQ,KAAK;IAGlD,8EAA8E;IACrE,iBAAiB,GAAG,IAAa,CAAC;IAE3C,YAAY,OAAe,EAAE,OAA2B;QACvD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,sEAAsE;QACtE,yCAAyC;QACzC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC7B,CAAC;CACD;AAED;;;;GAIG;AACH,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IACpD,IAAI,GAAG,wBAAwB,CAAC;IACzC,6DAA6D;IACpD,OAAO,CAAS;IAEzB,YACC,OAAe,EACf,UAAkB,OAAO,OAAO,mCAAmC,EACnE,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,6BAA8B,SAAQ,eAAe;IACxD,IAAI,GAAG,4BAA4B,CAAC;IAC7C,kEAAkE;IACzD,UAAU,CAAS;IAE5B,YACC,UAAU,GAAG,YAAY,EACzB,UAAkB,+CAA+C,UAAU,6DAA6D,UAAU,aAAa,UAAU,+GAA+G,EACxR,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;CACD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IAC5C,IAAI,GAAG,eAAe,CAAC;IAChC,6EAA6E;IACpE,KAAK,CAAS;IAEvB,YACC,KAAa,EACb,UAAkB,yBAAyB,IAAI,CAAC,SAAS,CACxD,KAAK,CACL,sJAAsJ,EACvJ,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC9C,IAAI,GAAG,iBAAiB,CAAC;IAClC,kDAAkD;IACzC,OAAO,CAAS;IACzB,kEAAkE;IACzD,UAAU,CAAS;IAE5B,YACC,OAAe,EACf,UAAkB,EAClB,UAAkB,QAAQ,OAAO,oDAAoD,UAAU,IAAI,EACnG,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;CACD;AAED;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,eAAe;IACjD,IAAI,GAAG,qBAAqB,CAAC;IACtC,4EAA4E;IACnE,OAAO,CAAS;IAEzB,YACC,OAAe,EACf,UAAkB,oDAAoD,OAAO,mFAAmF,EAChK,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,eAAe;IAC/C,IAAI,GAAG,mBAAmB,CAAC;IACpC,qDAAqD;IAC5C,QAAQ,CAAS;IAE1B,YACC,QAAgB,EAChB,UAAkB,+CAA+C,QAAQ,+DAA+D,EACxI,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,CAAC;CACD;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IAC5C,IAAI,GAAG,gBAAgB,CAAC;IAEjC,YACC,UAAkB,2EAA2E,EAC7F,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IACpD,IAAI,GAAG,wBAAwB,CAAC;IAEzC,YACC,UAAkB,0DAA0D,EAC5E,OAA2B;QAE3B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;CACD;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC/C,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAuC,CAAC,iBAAiB,KAAK,IAAI;QACnE,OAAQ,KAA0B,CAAC,IAAI,KAAK,QAAQ,CACpD,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -5,9 +5,10 @@ export { StubTransport, type StubCall } from './stub-transport.js';
 export type { Hand, HandContext, HandContribution } from './hand-host.js';
 export { readHandsConfig, normalizeConfig, loadHands, HandLoadError, HANDS_CONFIG_FILENAME, type HandEntry, type HandsConfig, type LoadedHand, type LoadHandsOptions, } from './hand-loading.js';
 export { PlaywrightLaunchTransport, type PlaywrightLaunchTransportOptions, type StealthChromiumImporter, } from './playwright-launch-transport.js';
+export { parseSocksProxy, hostResolverRulesArg, type ParsedSocksProxy, } from './socks-proxy.js';
 export { PlaywrightAttachTransport } from './playwright-attach-transport.js';
 export { setupProfile, buildPrompt, type PromptSink, type SetupProfileOptions, type SetupProfileResult, } from './setup-profile.js';
-export { ControllerError, MissingBrowserBinaryError, MissingStealthDependencyError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, isControllerError, type ControllerErrorCode, } from './errors.js';
+export { ControllerError, MissingBrowserBinaryError, MissingStealthDependencyError, InvalidProxyError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, isControllerError, type ControllerErrorCode, } from './errors.js';
 export { resolveSessionEndpointPath, writeSessionEndpoint, readSessionEndpoint, clearSessionEndpoint, SESSION_ENDPOINT_FILENAME, type SessionEndpoint, } from './session-endpoint.js';
 export { startSessionServer, sessionAlreadyActive, type SessionServerOptions, type RunningSessionServer, } from './session-server.js';
 export { connectRemoteSession } from './remote-session.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,MAAM,EACN,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAEjE,YAAY,EAAC,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,uBAAuB,GAC5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,EACX,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,MAAM,EACN,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,aAAa,GAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAE,KAAK,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAEjE,YAAY,EAAC,IAAI,EAAE,WAAW,EAAE,gBAAgB,EAAC,MAAM,gBAAgB,CAAC;AAExE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,GACrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,yBAAyB,EACzB,KAAK,gCAAgC,EACrC,KAAK,uBAAuB,GAC5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACN,eAAe,EACf,oBAAoB,EACpB,KAAK,gBAAgB,GACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,EACX,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACvB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,KAAK,eAAe,GACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,GACzB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,KAAK,aAAa,GAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}

package/dist/index.js

@@ -3,9 +3,10 @@ export { serializeCookies, deserializeCookies, COOKIES_EXPORT_VERSION, } from '.
 export { StubTransport } from './stub-transport.js';
 export { readHandsConfig, normalizeConfig, loadHands, HandLoadError, HANDS_CONFIG_FILENAME, } from './hand-loading.js';
 export { PlaywrightLaunchTransport, } from './playwright-launch-transport.js';
+export { parseSocksProxy, hostResolverRulesArg, } from './socks-proxy.js';
 export { PlaywrightAttachTransport } from './playwright-attach-transport.js';
 export { setupProfile, buildPrompt, } from './setup-profile.js';
-export { ControllerError, MissingBrowserBinaryError, MissingStealthDependencyError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, isControllerError, } from './errors.js';
+export { ControllerError, MissingBrowserBinaryError, MissingStealthDependencyError, InvalidProxyError, MissingProfileError, AttachNotChromiumError, AttachNoContextError, NoLiveServerError, SessionAlreadyActiveError, isControllerError, } from './errors.js';
 export { resolveSessionEndpointPath, writeSessionEndpoint, readSessionEndpoint, clearSessionEndpoint, SESSION_ENDPOINT_FILENAME, } from './session-endpoint.js';
 export { startSessionServer, sessionAlreadyActive, } from './session-server.js';
 export { connectRemoteSession } from './remote-session.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAIjE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,GAKrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,yBAAyB,GAGzB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,GAEjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,GAEzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,GAGpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,GAKZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,GAElB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAC;AAElC,OAAO,EACN,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,GAEtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AAIjE,OAAO,EACN,eAAe,EACf,eAAe,EACf,SAAS,EACT,aAAa,EACb,qBAAqB,GAKrB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACN,yBAAyB,GAGzB,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACN,eAAe,EACf,oBAAoB,GAEpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAC,yBAAyB,EAAC,MAAM,kCAAkC,CAAC;AAE3E,OAAO,EACN,YAAY,EACZ,WAAW,GAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACN,eAAe,EACf,yBAAyB,EACzB,6BAA6B,EAC7B,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,GAEjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,GAEzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,EAClB,oBAAoB,GAGpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAC,oBAAoB,EAAC,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACN,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,YAAY,GAKZ,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACN,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GAGhB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,kBAAkB,GAElB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAC,aAAa,EAAC,MAAM,kCAAkC,CAAC"}

package/dist/playwright-launch-transport.d.ts

@@ -103,6 +103,29 @@ export interface PlaywrightLaunchTransportOptions {
      * Default: none.
      */
     readonly ignoreDefaultArgs?: boolean | readonly string[];
+    /**
+     * Route ALL browser traffic AND DNS through a single SOCKS proxy, given as a
+     * SOCKS URL: `socks5h://host:1080` (or `socks5://host:1080`, optionally with a
+     * `user:pass@` userinfo). When set, the transport forwards the proxy to
+     * Playwright's `proxy` launch option AND adds Chromium's `--host-resolver-rules`
+     * catch-all so no DNS query escapes locally (see {@link proxyNoLeak}).
+     *
+     * Scheme convention: `socks5h://` means "resolve DNS at the proxy" (no leak),
+     * `socks5://` means "SOCKS5, local DNS allowed" (Chromium still resolves URL
+     * hostnames at the proxy, but its DNS prefetcher etc. may issue local DNS). Use
+     * {@link proxyNoLeak} to override the scheme's implied DNS behaviour. A
+     * malformed value throws the typed {@link InvalidProxyError} rather than
+     * launching unproxied. Default: no proxy.
+     */
+    readonly proxy?: string;
+    /**
+     * Override whether the {@link proxy} enforces NO local DNS. `true` forces the
+     * leak-free catch-all even for a plain `socks5://` URL; `false` allows local
+     * DNS even for a `socks5h://` URL. When omitted, the SCHEME decides
+     * (`socks5h` => no leak, `socks5`/`socks` => local DNS allowed). Ignored when
+     * {@link proxy} is unset.
+     */
+    readonly proxyNoLeak?: boolean;
     /**
      * INTERNAL test seam: override how the stealth chromium is imported. Omit in
      * production (defaults to `import('patchright')`). See

package/dist/playwright-launch-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.d.ts","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAiC,MAAM,YAAY,CAAC;AAMpE,OAAO,EAAmB,KAAK,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAE9D;;;;;;;;GAQG;AACH,KAAK,gBAAgB,GAAG,IAAI,CAAC,OAAO,QAAQ,EAAE,yBAAyB,CAAC,CAAC;AAEzE,oEAAoE;AACpE,UAAU,aAAa;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,gCAAgC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;IACzD;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;CACzD;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAU1D;;;;;;;;;;;;;;OAcG;gBAEF,QAAQ,GAAE,sBAA2B,EACrC,KAAK,GAAE,SAAS,IAAI,EAAO,EAC3B,OAAO,GAAE,gCAAqC;IAazC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAyHhD"}
+{"version":3,"file":"playwright-launch-transport.d.ts","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,QAAQ,EAAiC,MAAM,YAAY,CAAC;AAMpE,OAAO,EAAmB,KAAK,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAEN,KAAK,sBAAsB,EAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAC,MAAM,WAAW,CAAC;AAE9D;;;;;;;;GAQG;AACH,KAAK,gBAAgB,GAAG,IAAI,CAAC,OAAO,QAAQ,EAAE,yBAAyB,CAAC,CAAC;AAEzE,oEAAoE;AACpE,UAAU,aAAa;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;AAEnE;;;;;;GAMG;AACH,MAAM,WAAW,gCAAgC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;IACzD;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;CACzD;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAY1D;;;;;;;;;;;;;;OAcG;gBAEF,QAAQ,GAAE,sBAA2B,EACrC,KAAK,GAAE,SAAS,IAAI,EAAO,EAC3B,OAAO,GAAE,gCAAqC;IAezC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA6IhD"}

package/dist/playwright-launch-transport.js

@@ -3,6 +3,7 @@ import { chromium } from 'playwright';
 import { MissingBrowserBinaryError, MissingProfileError, MissingStealthDependencyError, } from './errors.js';
 import { composeWithHands } from './hand-host.js';
 import { resolveProfileLocation, } from './profile-location.js';
+import { hostResolverRulesArg, parseSocksProxy } from './socks-proxy.js';
 /**
  * The package name of the optional stealth dependency. Kept as a runtime value
  * (not an `import('patchright')` literal) so TypeScript does NOT try to resolve
@@ -50,6 +51,8 @@ export class PlaywrightLaunchTransport {
     #noViewport;
     #extraLaunchArgs;
     #ignoreDefaultArgs;
+    #proxy;
+    #proxyNoLeak;
     #importStealthChromium;
     /**
      * @param location overrides for where profiles live (a `root` dir and/or an
@@ -74,6 +77,8 @@ export class PlaywrightLaunchTransport {
         this.#noViewport = options.noViewport;
         this.#extraLaunchArgs = options.extraLaunchArgs;
         this.#ignoreDefaultArgs = options.ignoreDefaultArgs;
+        this.#proxy = options.proxy;
+        this.#proxyNoLeak = options.proxyNoLeak;
         this.#importStealthChromium =
             options.importStealthChromium ?? defaultStealthImporter;
     }
@@ -129,13 +134,33 @@ export class PlaywrightLaunchTransport {
         else if (this.#stealth) {
             launchOptions.ignoreDefaultArgs = ['--enable-automation'];
         }
+        // Proxy: route ALL traffic + DNS through one SOCKS proxy. We parse the URL
+        // HERE (a malformed value is the typed InvalidProxyError, never a silent
+        // unproxied launch), forward it to Playwright's `proxy` option, and when
+        // no-leak is in effect add Chromium's --host-resolver-rules catch-all so even
+        // the DNS prefetcher cannot leak a raw local DNS query.
+        const hardeningArgs = [];
+        if (this.#proxy !== undefined && this.#proxy.trim() !== '') {
+            const parsed = parseSocksProxy(this.#proxy, this.#proxyNoLeak);
+            launchOptions.proxy = {
+                server: parsed.server,
+                ...(parsed.username !== undefined ? { username: parsed.username } : {}),
+                ...(parsed.password !== undefined ? { password: parsed.password } : {}),
+            };
+            if (parsed.noLeak) {
+                hardeningArgs.push(hostResolverRulesArg(parsed.host));
+            }
+        }
         // Extra launch args (the hardening escape hatch) are appended verbatim. We do
         // NOT set user-agent/locale/timezone/headers here: a wrong UA is a bigger
         // tell than none (Patchright warns against overriding them), so those stay
-        // untouched by default.
+        // untouched by default. The proxy's no-leak DNS arg (if any) rides alongside.
         if (this.#extraLaunchArgs !== undefined &&
             this.#extraLaunchArgs.length > 0) {
-            launchOptions.args = [...this.#extraLaunchArgs];
+            hardeningArgs.push(...this.#extraLaunchArgs);
+        }
+        if (hardeningArgs.length > 0) {
+            launchOptions.args = hardeningArgs;
         }
         let context;
         try {

package/dist/playwright-launch-transport.js.map

@@ -1 +1 @@
-{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"playwright-launch-transport.js","sourceRoot":"","sources":["../src/playwright-launch-transport.ts"],"names":[],"mappings":"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"}

package/dist/socks-proxy.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A parsed SOCKS proxy ready to hand to Playwright/Chromium.
+ *
+ * This is the SINGLE place webhands turns a user-facing `--proxy` SOCKS URL into
+ * the concrete launch inputs Chromium needs: the `proxy.server`/credentials
+ * Playwright forwards, plus the extra command-line arg that forces DNS through
+ * the proxy (no DNS leak). Keeping the brittle parsing + Chromium-flag knowledge
+ * in one module mirrors how the launch transport confines its other
+ * Playwright/Chromium details.
+ */
+export interface ParsedSocksProxy {
+    /**
+     * The Playwright `proxy.server` value, always normalized to `socks5://host:port`.
+     *
+     * Chromium's `--proxy-server` understands `socks5://` but NOT the `socks5h://`
+     * convention, so we normalize the scheme here and carry the "resolve DNS at
+     * the proxy / block local DNS" intent separately in {@link noLeak} instead of
+     * in the scheme string.
+     */
+    readonly server: string;
+    /** Optional proxy username (from a `user:pass@` userinfo component). */
+    readonly username?: string;
+    /** Optional proxy password (from a `user:pass@` userinfo component). */
+    readonly password?: string;
+    /** The proxy host, used to build the DNS catch-all EXCLUDE rule. */
+    readonly host: string;
+    /**
+     * Whether to enforce NO local DNS (force every hostname to resolve at the
+     * proxy). When `true`, the transport adds a `--host-resolver-rules` catch-all
+     * so even Chromium components that bypass `--proxy-server` (DNS prefetcher,
+     * etc.) cannot leak a raw DNS query (see {@link hostResolverRulesArg}).
+     */
+    readonly noLeak: boolean;
+}
+/**
+ * Parse a user-facing `--proxy` SOCKS URL into a {@link ParsedSocksProxy}.
+ *
+ * Accepts `socks5h://`, `socks5://`, or `socks://` with a host and port and an
+ * optional `user:pass@` userinfo. Anything else (missing host/port, an http(s)
+ * proxy, a bare host with no scheme) is a typed {@link InvalidProxyError} so the
+ * caller refuses LOUDLY rather than launching unproxied.
+ *
+ * `forceNoLeak`, when set, overrides the scheme's implied DNS behaviour: pass
+ * `true` to enforce no local DNS even for a plain `socks5://` URL, or `false` to
+ * allow local DNS even for `socks5h://`. When omitted, the SCHEME decides
+ * (`socks5h` => no-leak, `socks5`/`socks` => local DNS allowed).
+ */
+export declare function parseSocksProxy(value: string, forceNoLeak?: boolean): ParsedSocksProxy;
+/**
+ * Build the Chromium `--host-resolver-rules` argument that prevents ANY local
+ * DNS resolution, the catch-all the Chromium SOCKS design doc prescribes for a
+ * leak-free SOCKS proxy.
+ *
+ * `MAP * ~NOTFOUND` maps every hostname to an invalid address so Chromium never
+ * issues a real local DNS query; `EXCLUDE <host>` lets Chromium still resolve
+ * the proxy server's own address (otherwise every request fails with
+ * PROXY_CONNECTION_FAILED). URL loads themselves resolve at the proxy via
+ * `--proxy-server`; this arg closes the side channels (DNS prefetcher, etc.).
+ */
+export declare function hostResolverRulesArg(host: string): string;
+//# sourceMappingURL=socks-proxy.d.ts.map

package/dist/socks-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socks-proxy.d.ts","sourceRoot":"","sources":["../src/socks-proxy.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAqBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,OAAO,GACnB,gBAAgB,CAuClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/socks-proxy.js

@@ -0,0 +1,84 @@
+import { InvalidProxyError } from './errors.js';
+/**
+ * The SOCKS schemes we accept on a `--proxy` value.
+ *
+ * - `socks5h://` is the widely-used convention meaning "resolve DNS at the
+ *   proxy" (no local DNS, no leak). We map it to {@link ParsedSocksProxy.noLeak}
+ *   `true`.
+ * - `socks5://` means "SOCKS5, local DNS allowed" by the same convention. NOTE:
+ *   Chromium ALREADY resolves URL hostnames at the proxy under `--proxy-server`,
+ *   but other components (the DNS prefetcher) can still issue raw local DNS, so
+ *   plain `socks5://` does NOT by itself guarantee no leak.
+ *
+ * `socks://` is accepted as an alias for `socks5://` (some tools emit it).
+ */
+const SCHEME_NO_LEAK = {
+    'socks5h:': true,
+    'socks5:': false,
+    'socks:': false,
+};
+/**
+ * Parse a user-facing `--proxy` SOCKS URL into a {@link ParsedSocksProxy}.
+ *
+ * Accepts `socks5h://`, `socks5://`, or `socks://` with a host and port and an
+ * optional `user:pass@` userinfo. Anything else (missing host/port, an http(s)
+ * proxy, a bare host with no scheme) is a typed {@link InvalidProxyError} so the
+ * caller refuses LOUDLY rather than launching unproxied.
+ *
+ * `forceNoLeak`, when set, overrides the scheme's implied DNS behaviour: pass
+ * `true` to enforce no local DNS even for a plain `socks5://` URL, or `false` to
+ * allow local DNS even for `socks5h://`. When omitted, the SCHEME decides
+ * (`socks5h` => no-leak, `socks5`/`socks` => local DNS allowed).
+ */
+export function parseSocksProxy(value, forceNoLeak) {
+    const trimmed = value.trim();
+    if (trimmed === '') {
+        throw new InvalidProxyError(value);
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch (cause) {
+        throw new InvalidProxyError(value, undefined, { cause });
+    }
+    const schemeNoLeak = SCHEME_NO_LEAK[url.protocol];
+    if (schemeNoLeak === undefined) {
+        // Not a SOCKS scheme (e.g. http://, https://, socks4://, or no scheme).
+        throw new InvalidProxyError(value);
+    }
+    if (url.hostname === '' || url.port === '') {
+        // A host AND an explicit port are both required: Chromium's --proxy-server
+        // needs the port, and we will not guess a default.
+        throw new InvalidProxyError(value);
+    }
+    const noLeak = forceNoLeak ?? schemeNoLeak;
+    const server = `socks5://${url.hostname}:${url.port}`;
+    const proxy = {
+        server,
+        host: url.hostname,
+        noLeak,
+        ...(url.username !== ''
+            ? { username: decodeURIComponent(url.username) }
+            : {}),
+        ...(url.password !== ''
+            ? { password: decodeURIComponent(url.password) }
+            : {}),
+    };
+    return proxy;
+}
+/**
+ * Build the Chromium `--host-resolver-rules` argument that prevents ANY local
+ * DNS resolution, the catch-all the Chromium SOCKS design doc prescribes for a
+ * leak-free SOCKS proxy.
+ *
+ * `MAP * ~NOTFOUND` maps every hostname to an invalid address so Chromium never
+ * issues a real local DNS query; `EXCLUDE <host>` lets Chromium still resolve
+ * the proxy server's own address (otherwise every request fails with
+ * PROXY_CONNECTION_FAILED). URL loads themselves resolve at the proxy via
+ * `--proxy-server`; this arg closes the side channels (DNS prefetcher, etc.).
+ */
+export function hostResolverRulesArg(host) {
+    return `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${host}`;
+}
+//# sourceMappingURL=socks-proxy.js.map

package/dist/socks-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socks-proxy.js","sourceRoot":"","sources":["../src/socks-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,iBAAiB,EAAC,MAAM,aAAa,CAAC;AAqC9C;;;;;;;;;;;;GAYG;AACH,MAAM,cAAc,GAAsC;IACzD,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;CACf,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC9B,KAAa,EACb,WAAqB;IAErB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACJ,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAC,KAAK,EAAC,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,YAAY,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAChC,wEAAwE;QACxE,MAAM,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAC5C,2EAA2E;QAC3E,mDAAmD;QACnD,MAAM,IAAI,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,IAAI,YAAY,CAAC;IAC3C,MAAM,MAAM,GAAG,YAAY,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;IAEtD,MAAM,KAAK,GAAqB;QAC/B,MAAM;QACN,IAAI,EAAE,GAAG,CAAC,QAAQ;QAClB,MAAM;QACN,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,EAAE;YACtB,CAAC,CAAC,EAAC,QAAQ,EAAE,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAC;YAC9C,CAAC,CAAC,EAAE,CAAC;QACN,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,EAAE;YACtB,CAAC,CAAC,EAAC,QAAQ,EAAE,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAC;YAC9C,CAAC,CAAC,EAAE,CAAC;KACN,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAChD,OAAO,mDAAmD,IAAI,EAAE,CAAC;AAClE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webhands/core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Core library for webhands: drives a real, persistent browser via Playwright.",
   "keywords": [
     "browser",

package/src/errors.ts

@@ -19,6 +19,7 @@
 export type ControllerErrorCode =
 	| 'missing-browser-binary'
 	| 'missing-stealth-dependency'
+	| 'invalid-proxy'
 	| 'missing-profile'
 	| 'attach-not-chromium'
 	| 'attach-no-context'
@@ -96,6 +97,35 @@ export class MissingStealthDependencyError extends ControllerError {
 	}
 }
 
+/**
+ * The `--proxy` value (a SOCKS URL) could not be parsed into a usable proxy
+ * config. webhands routes ALL traffic and DNS through one SOCKS proxy, so the
+ * value must be a `socks5://` or `socks5h://` URL with a host and port (an
+ * optional `user:pass@` is allowed). We refuse a malformed value LOUDLY with
+ * this typed condition rather than silently launching with no proxy (which
+ * would leak the very traffic the user asked to tunnel). The CLI maps the
+ * {@link code} to a fix message showing the expected URL shape.
+ *
+ * Mirrors {@link MissingStealthDependencyError}: a stable typed error whose
+ * brittle detection is confined to one spot (the proxy parser).
+ */
+export class InvalidProxyError extends ControllerError {
+	readonly code = 'invalid-proxy';
+	/** The offending raw `--proxy` value, echoed back so the user can see it. */
+	readonly value: string;
+
+	constructor(
+		value: string,
+		message: string = `Invalid --proxy value ${JSON.stringify(
+			value,
+		)}. Expected a SOCKS URL like socks5h://host:1080 or socks5://user:pass@host:1080 (socks5h tunnels DNS too; both route all traffic through the proxy).`,
+		options?: {cause?: unknown},
+	) {
+		super(message, options);
+		this.value = value;
+	}
+}
+
 /**
  * The named profile has not been set up yet: its dedicated profile directory
  * does not exist on disk. A profile is created by the headed `setup-profile`

package/src/index.ts

@@ -42,6 +42,12 @@ export {
 	type StealthChromiumImporter,
 } from './playwright-launch-transport.js';
 
+export {
+	parseSocksProxy,
+	hostResolverRulesArg,
+	type ParsedSocksProxy,
+} from './socks-proxy.js';
+
 export {PlaywrightAttachTransport} from './playwright-attach-transport.js';
 
 export {
@@ -56,6 +62,7 @@ export {
 	ControllerError,
 	MissingBrowserBinaryError,
 	MissingStealthDependencyError,
+	InvalidProxyError,
 	MissingProfileError,
 	AttachNotChromiumError,
 	AttachNoContextError,

package/src/playwright-launch-transport.ts

@@ -10,6 +10,7 @@ import {
 	resolveProfileLocation,
 	type ProfileLocationOptions,
 } from './profile-location.js';
+import {hostResolverRulesArg, parseSocksProxy} from './socks-proxy.js';
 import type {OpenTarget, Session, Transport} from './seam.js';
 
 /**
@@ -116,6 +117,29 @@ export interface PlaywrightLaunchTransportOptions {
 	 * Default: none.
 	 */
 	readonly ignoreDefaultArgs?: boolean | readonly string[];
+	/**
+	 * Route ALL browser traffic AND DNS through a single SOCKS proxy, given as a
+	 * SOCKS URL: `socks5h://host:1080` (or `socks5://host:1080`, optionally with a
+	 * `user:pass@` userinfo). When set, the transport forwards the proxy to
+	 * Playwright's `proxy` launch option AND adds Chromium's `--host-resolver-rules`
+	 * catch-all so no DNS query escapes locally (see {@link proxyNoLeak}).
+	 *
+	 * Scheme convention: `socks5h://` means "resolve DNS at the proxy" (no leak),
+	 * `socks5://` means "SOCKS5, local DNS allowed" (Chromium still resolves URL
+	 * hostnames at the proxy, but its DNS prefetcher etc. may issue local DNS). Use
+	 * {@link proxyNoLeak} to override the scheme's implied DNS behaviour. A
+	 * malformed value throws the typed {@link InvalidProxyError} rather than
+	 * launching unproxied. Default: no proxy.
+	 */
+	readonly proxy?: string;
+	/**
+	 * Override whether the {@link proxy} enforces NO local DNS. `true` forces the
+	 * leak-free catch-all even for a plain `socks5://` URL; `false` allows local
+	 * DNS even for a `socks5h://` URL. When omitted, the SCHEME decides
+	 * (`socks5h` => no leak, `socks5`/`socks` => local DNS allowed). Ignored when
+	 * {@link proxy} is unset.
+	 */
+	readonly proxyNoLeak?: boolean;
 	/**
 	 * INTERNAL test seam: override how the stealth chromium is imported. Omit in
 	 * production (defaults to `import('patchright')`). See
@@ -173,6 +197,8 @@ export class PlaywrightLaunchTransport implements Transport {
 	readonly #noViewport: boolean | undefined;
 	readonly #extraLaunchArgs: readonly string[] | undefined;
 	readonly #ignoreDefaultArgs: boolean | readonly string[] | undefined;
+	readonly #proxy: string | undefined;
+	readonly #proxyNoLeak: boolean | undefined;
 	readonly #importStealthChromium: StealthChromiumImporter;
 
 	/**
@@ -202,6 +228,8 @@ export class PlaywrightLaunchTransport implements Transport {
 		this.#noViewport = options.noViewport;
 		this.#extraLaunchArgs = options.extraLaunchArgs;
 		this.#ignoreDefaultArgs = options.ignoreDefaultArgs;
+		this.#proxy = options.proxy;
+		this.#proxyNoLeak = options.proxyNoLeak;
 		this.#importStealthChromium =
 			options.importStealthChromium ?? defaultStealthImporter;
 	}
@@ -266,15 +294,35 @@ export class PlaywrightLaunchTransport implements Transport {
 		} else if (this.#stealth) {
 			launchOptions.ignoreDefaultArgs = ['--enable-automation'];
 		}
+		// Proxy: route ALL traffic + DNS through one SOCKS proxy. We parse the URL
+		// HERE (a malformed value is the typed InvalidProxyError, never a silent
+		// unproxied launch), forward it to Playwright's `proxy` option, and when
+		// no-leak is in effect add Chromium's --host-resolver-rules catch-all so even
+		// the DNS prefetcher cannot leak a raw local DNS query.
+		const hardeningArgs: string[] = [];
+		if (this.#proxy !== undefined && this.#proxy.trim() !== '') {
+			const parsed = parseSocksProxy(this.#proxy, this.#proxyNoLeak);
+			launchOptions.proxy = {
+				server: parsed.server,
+				...(parsed.username !== undefined ? {username: parsed.username} : {}),
+				...(parsed.password !== undefined ? {password: parsed.password} : {}),
+			};
+			if (parsed.noLeak) {
+				hardeningArgs.push(hostResolverRulesArg(parsed.host));
+			}
+		}
 		// Extra launch args (the hardening escape hatch) are appended verbatim. We do
 		// NOT set user-agent/locale/timezone/headers here: a wrong UA is a bigger
 		// tell than none (Patchright warns against overriding them), so those stay
-		// untouched by default.
+		// untouched by default. The proxy's no-leak DNS arg (if any) rides alongside.
 		if (
 			this.#extraLaunchArgs !== undefined &&
 			this.#extraLaunchArgs.length > 0
 		) {
-			launchOptions.args = [...this.#extraLaunchArgs];
+			hardeningArgs.push(...this.#extraLaunchArgs);
+		}
+		if (hardeningArgs.length > 0) {
+			launchOptions.args = hardeningArgs;
 		}
 
 		let context: BrowserContext;

package/src/socks-proxy.ts

@@ -0,0 +1,127 @@
+import {InvalidProxyError} from './errors.js';
+
+/**
+ * A parsed SOCKS proxy ready to hand to Playwright/Chromium.
+ *
+ * This is the SINGLE place webhands turns a user-facing `--proxy` SOCKS URL into
+ * the concrete launch inputs Chromium needs: the `proxy.server`/credentials
+ * Playwright forwards, plus the extra command-line arg that forces DNS through
+ * the proxy (no DNS leak). Keeping the brittle parsing + Chromium-flag knowledge
+ * in one module mirrors how the launch transport confines its other
+ * Playwright/Chromium details.
+ */
+export interface ParsedSocksProxy {
+	/**
+	 * The Playwright `proxy.server` value, always normalized to `socks5://host:port`.
+	 *
+	 * Chromium's `--proxy-server` understands `socks5://` but NOT the `socks5h://`
+	 * convention, so we normalize the scheme here and carry the "resolve DNS at
+	 * the proxy / block local DNS" intent separately in {@link noLeak} instead of
+	 * in the scheme string.
+	 */
+	readonly server: string;
+	/** Optional proxy username (from a `user:pass@` userinfo component). */
+	readonly username?: string;
+	/** Optional proxy password (from a `user:pass@` userinfo component). */
+	readonly password?: string;
+	/** The proxy host, used to build the DNS catch-all EXCLUDE rule. */
+	readonly host: string;
+	/**
+	 * Whether to enforce NO local DNS (force every hostname to resolve at the
+	 * proxy). When `true`, the transport adds a `--host-resolver-rules` catch-all
+	 * so even Chromium components that bypass `--proxy-server` (DNS prefetcher,
+	 * etc.) cannot leak a raw DNS query (see {@link hostResolverRulesArg}).
+	 */
+	readonly noLeak: boolean;
+}
+
+/**
+ * The SOCKS schemes we accept on a `--proxy` value.
+ *
+ * - `socks5h://` is the widely-used convention meaning "resolve DNS at the
+ *   proxy" (no local DNS, no leak). We map it to {@link ParsedSocksProxy.noLeak}
+ *   `true`.
+ * - `socks5://` means "SOCKS5, local DNS allowed" by the same convention. NOTE:
+ *   Chromium ALREADY resolves URL hostnames at the proxy under `--proxy-server`,
+ *   but other components (the DNS prefetcher) can still issue raw local DNS, so
+ *   plain `socks5://` does NOT by itself guarantee no leak.
+ *
+ * `socks://` is accepted as an alias for `socks5://` (some tools emit it).
+ */
+const SCHEME_NO_LEAK: Readonly<Record<string, boolean>> = {
+	'socks5h:': true,
+	'socks5:': false,
+	'socks:': false,
+};
+
+/**
+ * Parse a user-facing `--proxy` SOCKS URL into a {@link ParsedSocksProxy}.
+ *
+ * Accepts `socks5h://`, `socks5://`, or `socks://` with a host and port and an
+ * optional `user:pass@` userinfo. Anything else (missing host/port, an http(s)
+ * proxy, a bare host with no scheme) is a typed {@link InvalidProxyError} so the
+ * caller refuses LOUDLY rather than launching unproxied.
+ *
+ * `forceNoLeak`, when set, overrides the scheme's implied DNS behaviour: pass
+ * `true` to enforce no local DNS even for a plain `socks5://` URL, or `false` to
+ * allow local DNS even for `socks5h://`. When omitted, the SCHEME decides
+ * (`socks5h` => no-leak, `socks5`/`socks` => local DNS allowed).
+ */
+export function parseSocksProxy(
+	value: string,
+	forceNoLeak?: boolean,
+): ParsedSocksProxy {
+	const trimmed = value.trim();
+	if (trimmed === '') {
+		throw new InvalidProxyError(value);
+	}
+
+	let url: URL;
+	try {
+		url = new URL(trimmed);
+	} catch (cause) {
+		throw new InvalidProxyError(value, undefined, {cause});
+	}
+
+	const schemeNoLeak = SCHEME_NO_LEAK[url.protocol];
+	if (schemeNoLeak === undefined) {
+		// Not a SOCKS scheme (e.g. http://, https://, socks4://, or no scheme).
+		throw new InvalidProxyError(value);
+	}
+	if (url.hostname === '' || url.port === '') {
+		// A host AND an explicit port are both required: Chromium's --proxy-server
+		// needs the port, and we will not guess a default.
+		throw new InvalidProxyError(value);
+	}
+
+	const noLeak = forceNoLeak ?? schemeNoLeak;
+	const server = `socks5://${url.hostname}:${url.port}`;
+
+	const proxy: ParsedSocksProxy = {
+		server,
+		host: url.hostname,
+		noLeak,
+		...(url.username !== ''
+			? {username: decodeURIComponent(url.username)}
+			: {}),
+		...(url.password !== ''
+			? {password: decodeURIComponent(url.password)}
+			: {}),
+	};
+	return proxy;
+}
+
+/**
+ * Build the Chromium `--host-resolver-rules` argument that prevents ANY local
+ * DNS resolution, the catch-all the Chromium SOCKS design doc prescribes for a
+ * leak-free SOCKS proxy.
+ *
+ * `MAP * ~NOTFOUND` maps every hostname to an invalid address so Chromium never
+ * issues a real local DNS query; `EXCLUDE <host>` lets Chromium still resolve
+ * the proxy server's own address (otherwise every request fails with
+ * PROXY_CONNECTION_FAILED). URL loads themselves resolve at the proxy via
+ * `--proxy-server`; this arg closes the side channels (DNS prefetcher, etc.).
+ */
+export function hostResolverRulesArg(host: string): string {
+	return `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${host}`;
+}