webhands 0.2.0 → 0.4.0

package/README.md

@@ -83,13 +83,31 @@ This is a **personal-use** tool. Its whole premise is that you drive a browser
 [`docs/adr/0002`](docs/adr/0002-real-session-over-fingerprint-spoofing.md)). It is
 deliberately local and single-session by design.
 
-- **No login-bypass, no CAPTCHA-solving.** The human does the one-time login and
-  clears any anti-bot challenge in the headed `setup-profile` step. This tool
-  does NOT bypass authentication or solve CAPTCHAs programmatically, and it is not
-  intended to.
+- **No login-bypass, no built-in CAPTCHA solver.** The human does the one-time
+  login and clears any anti-bot challenge in the headed `setup-profile` step.
+  webhands ships NO captcha solver and NO provider key, and does not bypass
+  authentication itself. What changed: the verb surface is now rich enough that it
+  no longer STANDS IN THE WAY of a capable agent that brings its OWN key. Such an
+  agent can get past a captcha by poking the page with verbs, both families: the
+  token-harvest family by reading the sitekey with a frame-aware `query`, `type`ing
+  a provider token into the response sink, and firing the callback; the vision/tile
+  family with the coordinate `mouse`, the element-clipped `screenshot`, and the
+  cross-origin frame read. We do not solve it; we no longer stand in the way. The
+  agent supplies its own key and its own logic (or uses a hand, below). webhands
+  is capable, not a solver.
+- **Hands are the simpler path (still).** A *hand* is a third-party capability
+  module (`iamhuman` today, a future buy-on-amazon hand) that closes over the live
+  page and makes the hard thing ONE call. A dumb agent plus a hand still gets there
+  in a single call, even though a capable agent can now do the same over several
+  verb turns. The two paths coexist: the verb surface is the floor that makes the
+  unaided path POSSIBLE; a hand is the ramp that makes it EASY. (A hand is a
+  trusted in-process peer, loaded only when you name it in `hands.json`; see
+  [`docs/adr/0007`](docs/adr/0007-public-hand-contract-and-explicit-declarative-loading.md).)
 - **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 +192,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/cli.d.ts

@@ -80,6 +80,12 @@ export interface LaunchPolicy {
      * to keep the fixed viewport even under stealth.
      */
     readonly noViewport?: boolean;
+    /**
+     * Route ALL traffic and DNS through one SOCKS proxy, as a SOCKS URL
+     * (`socks5h://host:1080` or `socks5://user:pass@host:1080`). `socks5h` tunnels
+     * DNS too (no leak); `socks5` allows local DNS. Omit for a direct connection.
+     */
+    readonly proxy?: string;
 }
 /**
  * Build the `incur` CLI that wraps `core`'s verb surface (PRD Implementation

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAC7B,OAAO,EACN,WAAW,EACX,sBAAsB,EAWtB,KAAK,UAAU,EACf,KAAK,oBAAoB,EAKzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAEN,KAAK,eAAe,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAG5C;;;;GAIG;AACH,eAAO,MAAM,QAAQ,aAAa,CAAC;AAMnC;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,4FAA4F;AAC5F,MAAM,WAAW,OAAO;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;KAAC,CAAC;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAC,EACjD,YAAY,CAAC,EAAE,YAAY,KACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC9B;AA2JD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,OAAY,gDAmiB3C;AA0ED,OAAO,EAAC,WAAW,EAAE,sBAAsB,EAAC,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAC7B,OAAO,EACN,WAAW,EACX,sBAAsB,EAYtB,KAAK,UAAU,EACf,KAAK,oBAAoB,EASzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAEN,KAAK,eAAe,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAG5C;;;;GAIG;AACH,eAAO,MAAM,QAAQ,aAAa,CAAC;AAMnC;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,4FAA4F;AAC5F,MAAM,WAAW,OAAO;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;KAAC,CAAC;IACzD;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAC,EACjD,YAAY,CAAC,EAAE,YAAY,KACvB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AA8KD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,OAAY,gDAsoC3C;AA8JD,OAAO,EAAC,WAAW,EAAE,sBAAsB,EAAC,CAAC"}