@webhands/core 0.3.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.
@@ -131,8 +133,18 @@ This is **off by default** — vanilla Playwright stays the default. To enable i
    Chrome with or without the Patchright path, and stealth with or without a
    system browser. Other channel names work too (e.g. `msedge`).
 
-Programmatic equivalent (the `--stealth` / `--use-system-browser` flags map onto
-these transport options):
+3. Optional extra hardening. `--no-viewport` lets the real browser window drive
+   its own size instead of Playwright's fixed 1280x720 emulated viewport (a
+   known headless tell). It is **defaulted ON under `--stealth`** (Patchright's
+   recommended recipe) and is overridable; pass `--viewport` to keep the fixed
+   viewport even under stealth. webhands deliberately does **not** override
+   `user-agent`, `locale`, `timezone`, or `headers`: a wrong UA is a bigger tell
+   than none.
+
+Programmatic equivalent (the `--stealth` / `--use-system-browser` /
+`--no-viewport` flags map onto these transport options; the constructor also
+takes `extraLaunchArgs` and `ignoreDefaultArgs` escape hatches for additional
+hardening flags, none of which touch the `OpenTarget` seam):
 
 ```ts
 import {PlaywrightLaunchTransport} from '@webhands/core';
@@ -140,7 +152,7 @@ import {PlaywrightLaunchTransport} from '@webhands/core';
 const transport = new PlaywrightLaunchTransport(
   {}, // profile location (omit for ~/.webhands)
   [], // extra hands
-  {stealth: true, systemBrowser: 'chrome'},
+  {stealth: true, systemBrowser: 'chrome'}, // noViewport defaults to true here
 );
 // Stealth + headed + a real logged-in profile is the strongest recipe:
 const session = await transport.open({
@@ -156,12 +168,59 @@ It **never silently falls back** to vanilla Playwright, because that would put
 the tell back without telling you.
 
 **Honest caveat.** Stealth addresses ONLY the CDP `Runtime.enable` automation
-tell. It is **necessary-but-not-sufficient**: IP reputation and session/profile
+tell, and the launch-hardening knobs (`--no-viewport`, `extraLaunchArgs`,
+`ignoreDefaultArgs`) reduce but do **not** eliminate detection. They are
+**necessary-but-not-sufficient**: IP reputation and session/profile
 reputation still matter. The realistic recipe is stealth +
 `systemBrowser: 'chrome'` + headed + a warmed, logged-in profile + a residential
 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":"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"}

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

@@ -56,6 +56,76 @@ export interface PlaywrightLaunchTransportOptions {
      * Playwright vocabulary out of the public surface).
      */
     readonly systemBrowser?: string;
+    /**
+     * Don't impose a fixed emulated viewport: let the browser window drive its own
+     * size, exactly as a real user's browser does. Maps to Playwright's
+     * `viewport: null` on the persistent context.
+     *
+     * Why this matters for hardening: Playwright's DEFAULT is a fixed 1280x720
+     * emulated viewport that does NOT match the real OS window, a discrepancy
+     * (e.g. `window.outerWidth`/`innerWidth`/`screen` mismatches, no real resize
+     * behaviour) that fingerprinting scripts read as a headless/automation tell.
+     * Patchright's official recommended recipe sets `no_viewport=True` for this
+     * reason.
+     *
+     * Default: `undefined` leaves Playwright's behaviour as-is, EXCEPT that when
+     * {@link stealth} is enabled it defaults to `true` (the Patchright recipe).
+     * Pass an explicit `false` to keep the fixed emulated viewport even under
+     * stealth (e.g. when a caller deliberately wants a deterministic size). We pick
+     * the stealth-on default because shipping the stealth engine while leaving the
+     * tell it is meant to hide in place would be self-defeating; making it an
+     * explicit, overridable default keeps that honest and discoverable.
+     */
+    readonly noViewport?: boolean;
+    /**
+     * Extra command-line args appended to the browser launch (Playwright's
+     * `args`). An escape hatch for well-known hardening flags Patchright/Chromium
+     * users pass (e.g. `--disable-blink-features=AutomationControlled`) WITHOUT
+     * leaking a Playwright type across the seam: this is a plain `string[]`, kept
+     * confined to this transport-construction policy and deliberately NOT on
+     * {@link OpenTarget} (ADR-0003). Default: none.
+     *
+     * Caveat: args are passed THROUGH verbatim; a wrong or contradictory flag can
+     * itself become a tell or break the launch. Opt-in only.
+     */
+    readonly extraLaunchArgs?: readonly string[];
+    /**
+     * Passthrough for Playwright's `ignoreDefaultArgs`: either `true` to drop ALL
+     * of Playwright's default launch args, or a list of specific default args to
+     * drop, so a caller can strip more automation-flavoured defaults than the
+     * built-in stealth subset.
+     *
+     * When omitted, the stealth path still drops `--enable-automation` on its own
+     * (unchanged behaviour). When provided, this value REPLACES that built-in
+     * choice, so a caller opting in owns the full list (pass
+     * `['--enable-automation', ...]` to keep it). Like {@link extraLaunchArgs}
+     * this is a plain value confined to this module, never on {@link OpenTarget}.
+     * 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
@@ -98,9 +168,11 @@ export declare class PlaywrightLaunchTransport implements Transport {
      *   the operator's explicit config; the transport does NOT discover them. Omit
      *   for the built-ins-only surface.
      * @param options transport-construction policy, notably the opt-in `stealth`
-     *   toggle and optional `systemBrowser` (see
+     *   toggle, optional `systemBrowser`, and the launch-hardening knobs
+     *   (`noViewport`, `extraLaunchArgs`, `ignoreDefaultArgs`; see
      *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
-     *   bundled Chromium, stealth OFF.
+     *   bundled Chromium, stealth OFF. The hardening knobs are confined to this
+     *   module and never reach {@link OpenTarget} (ADR-0003).
      */
     constructor(location?: ProfileLocationOptions, hands?: readonly Hand[], options?: PlaywrightLaunchTransportOptions);
     open(target: OpenTarget): Promise<Session>;

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;;;;OAIG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;CACzD;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,yBAA0B,YAAW,SAAS;;IAO1D;;;;;;;;;;;;OAYG;gBAEF,QAAQ,GAAE,sBAA2B,EACrC,KAAK,GAAE,SAAS,IAAI,EAAO,EAC3B,OAAO,GAAE,gCAAqC;IAUzC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CA8FhD"}
+{"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
@@ -47,6 +48,11 @@ export class PlaywrightLaunchTransport {
     #hands;
     #stealth;
     #systemBrowser;
+    #noViewport;
+    #extraLaunchArgs;
+    #ignoreDefaultArgs;
+    #proxy;
+    #proxyNoLeak;
     #importStealthChromium;
     /**
      * @param location overrides for where profiles live (a `root` dir and/or an
@@ -57,15 +63,22 @@ export class PlaywrightLaunchTransport {
      *   the operator's explicit config; the transport does NOT discover them. Omit
      *   for the built-ins-only surface.
      * @param options transport-construction policy, notably the opt-in `stealth`
-     *   toggle and optional `systemBrowser` (see
+     *   toggle, optional `systemBrowser`, and the launch-hardening knobs
+     *   (`noViewport`, `extraLaunchArgs`, `ignoreDefaultArgs`; see
      *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
-     *   bundled Chromium, stealth OFF.
+     *   bundled Chromium, stealth OFF. The hardening knobs are confined to this
+     *   module and never reach {@link OpenTarget} (ADR-0003).
      */
     constructor(location = {}, hands = [], options = {}) {
         this.#location = location;
         this.#hands = hands;
         this.#stealth = options.stealth === true;
         this.#systemBrowser = options.systemBrowser;
+        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;
     }
@@ -100,9 +113,55 @@ export class PlaywrightLaunchTransport {
         if (this.#systemBrowser !== undefined) {
             launchOptions.channel = this.#systemBrowser;
         }
-        if (this.#stealth) {
+        // no_viewport: explicit caller choice wins; otherwise default to TRUE under
+        // stealth (Patchright's recommended recipe), and leave Playwright's default
+        // fixed viewport in place when stealth is off. `viewport: null` is how
+        // Playwright expresses "let the real window drive the size".
+        const noViewport = this.#noViewport ?? this.#stealth;
+        if (noViewport) {
+            launchOptions.viewport = null;
+        }
+        // ignoreDefaultArgs: an explicit passthrough REPLACES the built-in stealth
+        // choice (the caller then owns the full list). With no passthrough, the
+        // stealth path keeps dropping just `--enable-automation` so it cannot re-add
+        // the fingerprint Patchright just removed.
+        if (this.#ignoreDefaultArgs !== undefined) {
+            launchOptions.ignoreDefaultArgs =
+                typeof this.#ignoreDefaultArgs === 'boolean'
+                    ? this.#ignoreDefaultArgs
+                    : [...this.#ignoreDefaultArgs];
+        }
+        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. The proxy's no-leak DNS arg (if any) rides alongside.
+        if (this.#extraLaunchArgs !== undefined &&
+            this.#extraLaunchArgs.length > 0) {
+            hardeningArgs.push(...this.#extraLaunchArgs);
+        }
+        if (hardeningArgs.length > 0) {
+            launchOptions.args = hardeningArgs;
+        }
         let context;
         try {
             context = await launcher.launchPersistentContext(loc.profileDir, launchOptions);

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.3.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';
 
 /**
@@ -69,6 +70,76 @@ export interface PlaywrightLaunchTransportOptions {
 	 * Playwright vocabulary out of the public surface).
 	 */
 	readonly systemBrowser?: string;
+	/**
+	 * Don't impose a fixed emulated viewport: let the browser window drive its own
+	 * size, exactly as a real user's browser does. Maps to Playwright's
+	 * `viewport: null` on the persistent context.
+	 *
+	 * Why this matters for hardening: Playwright's DEFAULT is a fixed 1280x720
+	 * emulated viewport that does NOT match the real OS window, a discrepancy
+	 * (e.g. `window.outerWidth`/`innerWidth`/`screen` mismatches, no real resize
+	 * behaviour) that fingerprinting scripts read as a headless/automation tell.
+	 * Patchright's official recommended recipe sets `no_viewport=True` for this
+	 * reason.
+	 *
+	 * Default: `undefined` leaves Playwright's behaviour as-is, EXCEPT that when
+	 * {@link stealth} is enabled it defaults to `true` (the Patchright recipe).
+	 * Pass an explicit `false` to keep the fixed emulated viewport even under
+	 * stealth (e.g. when a caller deliberately wants a deterministic size). We pick
+	 * the stealth-on default because shipping the stealth engine while leaving the
+	 * tell it is meant to hide in place would be self-defeating; making it an
+	 * explicit, overridable default keeps that honest and discoverable.
+	 */
+	readonly noViewport?: boolean;
+	/**
+	 * Extra command-line args appended to the browser launch (Playwright's
+	 * `args`). An escape hatch for well-known hardening flags Patchright/Chromium
+	 * users pass (e.g. `--disable-blink-features=AutomationControlled`) WITHOUT
+	 * leaking a Playwright type across the seam: this is a plain `string[]`, kept
+	 * confined to this transport-construction policy and deliberately NOT on
+	 * {@link OpenTarget} (ADR-0003). Default: none.
+	 *
+	 * Caveat: args are passed THROUGH verbatim; a wrong or contradictory flag can
+	 * itself become a tell or break the launch. Opt-in only.
+	 */
+	readonly extraLaunchArgs?: readonly string[];
+	/**
+	 * Passthrough for Playwright's `ignoreDefaultArgs`: either `true` to drop ALL
+	 * of Playwright's default launch args, or a list of specific default args to
+	 * drop, so a caller can strip more automation-flavoured defaults than the
+	 * built-in stealth subset.
+	 *
+	 * When omitted, the stealth path still drops `--enable-automation` on its own
+	 * (unchanged behaviour). When provided, this value REPLACES that built-in
+	 * choice, so a caller opting in owns the full list (pass
+	 * `['--enable-automation', ...]` to keep it). Like {@link extraLaunchArgs}
+	 * this is a plain value confined to this module, never on {@link OpenTarget}.
+	 * 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
@@ -123,6 +194,11 @@ export class PlaywrightLaunchTransport implements Transport {
 	readonly #hands: readonly Hand[];
 	readonly #stealth: boolean;
 	readonly #systemBrowser: string | undefined;
+	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;
 
 	/**
@@ -134,9 +210,11 @@ export class PlaywrightLaunchTransport implements Transport {
 	 *   the operator's explicit config; the transport does NOT discover them. Omit
 	 *   for the built-ins-only surface.
 	 * @param options transport-construction policy, notably the opt-in `stealth`
-	 *   toggle and optional `systemBrowser` (see
+	 *   toggle, optional `systemBrowser`, and the launch-hardening knobs
+	 *   (`noViewport`, `extraLaunchArgs`, `ignoreDefaultArgs`; see
 	 *   {@link PlaywrightLaunchTransportOptions}). Defaults to vanilla Playwright,
-	 *   bundled Chromium, stealth OFF.
+	 *   bundled Chromium, stealth OFF. The hardening knobs are confined to this
+	 *   module and never reach {@link OpenTarget} (ADR-0003).
 	 */
 	constructor(
 		location: ProfileLocationOptions = {},
@@ -147,6 +225,11 @@ export class PlaywrightLaunchTransport implements Transport {
 		this.#hands = hands;
 		this.#stealth = options.stealth === true;
 		this.#systemBrowser = options.systemBrowser;
+		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;
 	}
@@ -191,9 +274,56 @@ export class PlaywrightLaunchTransport implements Transport {
 		if (this.#systemBrowser !== undefined) {
 			launchOptions.channel = this.#systemBrowser;
 		}
-		if (this.#stealth) {
+		// no_viewport: explicit caller choice wins; otherwise default to TRUE under
+		// stealth (Patchright's recommended recipe), and leave Playwright's default
+		// fixed viewport in place when stealth is off. `viewport: null` is how
+		// Playwright expresses "let the real window drive the size".
+		const noViewport = this.#noViewport ?? this.#stealth;
+		if (noViewport) {
+			launchOptions.viewport = null;
+		}
+		// ignoreDefaultArgs: an explicit passthrough REPLACES the built-in stealth
+		// choice (the caller then owns the full list). With no passthrough, the
+		// stealth path keeps dropping just `--enable-automation` so it cannot re-add
+		// the fingerprint Patchright just removed.
+		if (this.#ignoreDefaultArgs !== undefined) {
+			launchOptions.ignoreDefaultArgs =
+				typeof this.#ignoreDefaultArgs === 'boolean'
+					? this.#ignoreDefaultArgs
+					: [...this.#ignoreDefaultArgs];
+		} 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. The proxy's no-leak DNS arg (if any) rides alongside.
+		if (
+			this.#extraLaunchArgs !== undefined &&
+			this.#extraLaunchArgs.length > 0
+		) {
+			hardeningArgs.push(...this.#extraLaunchArgs);
+		}
+		if (hardeningArgs.length > 0) {
+			launchOptions.args = hardeningArgs;
+		}
 
 		let context: BrowserContext;
 		try {

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}`;
+}