capskip 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,90 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-11-01
+
+### Added
+
+- **AWS WAF support** via `amazonWaf(sitekey, url, options)`, sent as
+  `method=amazon_waf`. Only `sitekey` and `url` are required.
+  On a challenge page (the HTTP 405 page with `window.gokuProps`), `sitekey`,
+  `iv` and `context` are `gokuProps.key`, `.iv` and `.context`, and
+  `challenge_script` / `captcha_script` are the page's challenge.js and
+  captcha.js. On a widget page (`AwsWafCaptcha.renderCaptcha`), `sitekey` is the
+  widget's `apiKey` and `jsapiScript` the URL of jsapi.js.
+  An AWS WAF answer is **not a token**: the result expands into
+  `captcha_voucher` and `existing_token`, which the site's `voucher` endpoint
+  (beside challenge.js) trades for the `aws-waf-token` cookie. `code` keeps the
+  raw answer.
+- Parameter aliases `challengeScript` for `challenge_script`, `captchaScript`
+  for `captcha_script`, and `jsapi_script` for `jsapiScript`.
+- TypeScript definitions for `AmazonWafOptions`, plus the new `SolveResult`
+  fields.
+- `examples/amazon_waf.js`.
+
+### Changed
+
+- The Capy answer expansion is now a shared helper, used by Capy and AWS WAF
+  alike. Capy results are unchanged.
+- The exported `version` constant now reports the package version; it had been
+  left at `1.1.0`.
+
+### Notes
+
+- `iv` and `context` are optional but travel together: one without the other is
+  refused locally, as the server would refuse it. Left out, CapSkip reads both
+  from the page at solve time. An optional passed as `''` is treated as not
+  sent, the way the server reads it.
+- Every script URL must be `https` on an `awswaf.com` host, with no credentials,
+  no port other than 443, and a path ending in `challenge.js`, `captcha.js` or
+  `jsapi.js`. CapSkip posts the solution to the host the script names, so any
+  other script is refused before the request is made.
+- AWS WAF uses `recaptchaTimeout`: a real browser mints the token the voucher is
+  issued for.
+
+## [1.3.0] - 2026-09-22
+
+### Added
+
+- **Capy Puzzle support** via `capy(sitekey, url, options)`. The site key
+  (conventionally prefixed `PUZZLE_`) is sent as the `captchakey` the API
+  documents. Optional `api_server` selects the Capy API the key lives behind,
+  defaulting to `https://jp.api.capy.me`.
+  A Capy answer is **not a token**: the result expands into `captchakey`,
+  `challengekey` and `answer`, which go into the target form's `capy_captchakey`,
+  `capy_challengekey` and `capy_answer` fields. `code` keeps the raw answer.
+- **CaptchaFox support** via `captchafox(sitekey, url, options)`. The result
+  exposes `token` (for the form's `cf-captcha-response` field) and, when the
+  solve reported one, `userAgent` — the UA the browser actually minted the token
+  under, which is not the one you sent. Optional `api_server` selects the widget
+  source; the MAM package returns a `MAM_` prefixed token.
+- **Friendly Captcha support** via `friendlyCaptcha(sitekey, url, options)`.
+  Pass `version` (`v1`/`v2`, or a bare `1`/`2`), or `moduleScript` /
+  `nomoduleScript` with the widget script URLs and let CapSkip read the version
+  off the build the site actually loads. Optional `api_server` accepts `global`
+  (the default), `eu`, or a full URL for the data-residency tenant. The result
+  exposes `token`, for `frc-captcha-solution` on v1 or `frc-captcha-response` on
+  v2.
+- Parameter aliases `userAgent`/`user_agent` for `useragent`, `captchaKey` for
+  `captchakey`, and `moduleScript`/`nomoduleScript` for `module_script` /
+  `nomodule_script`.
+- TypeScript definitions for `CapyOptions`, `CaptchaFoxOptions` and
+  `FriendlyCaptchaOptions`, plus the new `SolveResult` fields.
+
+### Notes
+
+- `version: 'avatar'` is refused locally for Capy. CapSkip solves the puzzle
+  family only, and answering an avatar request with a puzzle answer would bill
+  for a solve the target site rejects, indistinguishably from a broken solver.
+- An unknown Friendly Captcha `version` is refused locally too. The two versions
+  are different protocols sharing one sitekey namespace, so solving the wrong one
+  returns a well-formed token the site rejects with nothing to indicate why.
+- CaptchaFox and Friendly Captcha use `recaptchaTimeout`: the first is a real
+  browser solve, and the second has its difficulty set per request by the service
+  (and always solves in a browser on v2). Capy uses `defaultTimeout` — it is one
+  HTTP fetch plus pixel math, held back to roughly two seconds because Capy
+  refuses answers that arrive faster than a human could have produced them.
+
 ## [1.2.0] - 2026-09-12
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Tests](https://github.com/capskip/capskip-node/actions/workflows/ci.yml/badge.svg)](https://github.com/capskip/capskip-node/actions/workflows/ci.yml)
 
-**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA and image captchas from Node.js.**
+**Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF and image captchas from Node.js.**
 
 Official Node.js client for [CapSkip](https://capskip.com), a **local captcha solver** that runs on your own machine. Licensed once, not billed per solve. TypeScript definitions included.
 
@@ -19,7 +19,7 @@ npm install capskip
 
 CapSkip is a desktop app. It does the solving on your machine and exposes the standard captcha-solver HTTP API — the same `in.php` / `res.php` endpoints every 2captcha-compatible client already speaks — on `127.0.0.1:8080`.
 
-This SDK is a thin wrapper over that API, with the method names you would expect: `normal()`, `recaptcha()`, `turnstile()`, `geetest()`, `altcha()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
+This SDK is a thin wrapper over that API, with the method names you would expect: `normal()`, `recaptcha()`, `turnstile()`, `geetest()`, `altcha()`, `capy()`, `captchafox()`, `friendlyCaptcha()`, `amazonWaf()`. Nothing leaves your network, and there is no credit balance to keep an eye on.
 
 ## Supported captcha types
 
@@ -35,6 +35,11 @@ This SDK is a thin wrapper over that API, with the method names you would expect
 | Cloudflare Turnstile (challenge page) | `solver.turnstile(sitekey, url, { data, pagedata })` |
 | **GeeTest v3 solver** (slide puzzle) | `solver.geetest(gt, challenge, url)` |
 | **ALTCHA solver** (proof-of-work) | `solver.altcha(url, { challengeUrl })` |
+| **Capy Puzzle solver** (slide puzzle) | `solver.capy(sitekey, url)` |
+| **CaptchaFox solver** (widget) | `solver.captchafox(sitekey, url)` |
+| **Friendly Captcha solver** (proof-of-work) | `solver.friendlyCaptcha(sitekey, url, { version })` |
+| **AWS WAF solver** (challenge page) | `solver.amazonWaf(sitekey, url, { iv, context })` |
+| AWS WAF (widget) | `solver.amazonWaf(sitekey, url, { jsapiScript })` |
 
 **hCaptcha and FunCaptcha/Arkose are not supported.** hCaptcha is the one people misidentify most often, since it also puts a `data-sitekey` on the widget — check for `class="h-captcha"` or a `js.hcaptcha.com` script before reaching for `recaptcha()`.
 
@@ -131,8 +136,9 @@ const solver = new CapSkip({
   host: '127.0.0.1',        // CapSkip host
   port: 8080,               // CapSkip port from app settings
   defaultTimeout: 120,      // seconds — image captcha polling timeout
-  recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest polling timeout
-                            // (ALTCHA uses defaultTimeout — CPU work, not a browser solve)
+  recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest / CaptchaFox /
+                            // Friendly Captcha / AWS WAF polling timeout
+                            // (ALTCHA and Capy use defaultTimeout — neither is a browser solve)
   pollingInterval: 5,       // max seconds between res.php polls (starts at 0.25s, backs off to this)
 });
 ```
@@ -230,7 +236,128 @@ result.token;
 Challenges expire fast — some sites inside two minutes — so fetch one
 immediately before solving and submit the token promptly.
 
-### With a proxy (reCAPTCHA, Turnstile, GeeTest & ALTCHA only)
+### Capy Puzzle
+
+A Capy solution is not a token. It is three values that together go into the
+target form, so post all three back exactly as returned.
+
+```js
+const result = await solver.capy(
+  'PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v',
+  'https://example.com/login',
+);
+
+// capy_captchakey, capy_challengekey and capy_answer respectively
+result.captchakey, result.challengekey, result.answer;
+```
+
+`answer` is the drag path the widget would have recorded — submit it verbatim,
+without trimming or re-encoding it. The challenge key is single-use and
+short-lived, so submit promptly rather than caching the three values.
+
+Pass `api_server` when the widget script points somewhere other than
+`https://jp.api.capy.me`. Only the `puzzle` family is solved; `version: 'avatar'`
+is refused rather than answered with a puzzle answer the site would reject.
+
+### CaptchaFox
+
+```js
+const result = await solver.captchafox(
+  'sk_xtNxpk6fCdFbxh1_xJeGflSdCE9tn99G',
+  'https://example.com/signup',
+);
+
+// Post this back in the form field the widget uses, named `cf-captcha-response`
+result.token;
+
+// The UA the token was minted under — submit under this one, not your own
+result.userAgent;
+```
+
+`url` has to be the page the widget actually runs on: CaptchaFox checks it
+against the domains the key is registered for and refuses a mismatch
+permanently, not intermittently.
+
+Pass `api_server` only when the page does not load the default widget. A page
+loading the MAM package expects a `MAM_` prefixed token, and sending the wrong
+source still succeeds — it just returns a token the site will not accept, which
+reads as a silent verification failure rather than an error.
+
+### Friendly Captcha
+
+Two different protocols ship under this name and a sitekey does not tell you
+which one a site uses, so say which — or send the widget script and let CapSkip
+read it off the build the site actually loads.
+
+```js
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { version: 'v2' },
+);
+
+// v1 → frc-captcha-solution, v2 → frc-captcha-response
+result.token;
+```
+
+```js
+// Or let the script URL decide the version
+const result = await solver.friendlyCaptcha(
+  'FCMGEMUD2M567T8G',
+  'https://example.com/signup',
+  { moduleScript: 'https://cdn.example.com/@friendlycaptcha/sdk@0.1.6/site.min.js' },
+);
+```
+
+Solving the wrong version returns a well-formed token the target site rejects,
+with nothing to indicate the version was the problem. With neither `version` nor
+a script URL, v1 is assumed. Pass `api_server: 'eu'` for a sitekey on the EU
+data-residency tenant. A v2 token is roughly six kilobytes, so size whatever
+carries it accordingly.
+
+### AWS WAF
+
+AWS WAF puts its CAPTCHA either on a **challenge page** — the HTTP 405
+interstitial that sets `window.gokuProps` — or in a **widget** an ordinary page
+renders with `AwsWafCaptcha.renderCaptcha`. Only `sitekey` and `url` are required.
+
+```js
+// Challenge page: sitekey, iv and context are gokuProps.key, .iv and .context
+const result = await solver.amazonWaf(
+  'AQIDAHjcYuEXAMPLEghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AHDh0IR5vgzHNceHYqZR+GOAAAAfjB8',
+  'https://example.com/protected',
+  {
+    iv: 'CgAFRDIjfgAAA5yY',
+    context: 'Rbp3r8fvbuhmrCqpUe8Mh1TLvs8OSKJZiSs2vCF4dt9rxVZI7xYJa2n5k/9r+XaXe7KUIu2I8nXTDHHkDvIOTDc2',
+    challenge_script: 'https://3f2a9c7d41b0.edge.sdk.awswaf.com/3f2a9c7d41b0/8e51d0c7a2f4/challenge.js',
+  },
+);
+
+// Widget page: sitekey is the widget's apiKey, plus the jsapi.js it loads
+const result = await solver.amazonWaf(
+  'Xr9kEXAMPLE2bWQx1vTq8LmZ0aYc4dHs7nFp3gJt6uKw5eRi9AbCdEfGh=_0_1',
+  'https://example.com/protected',
+  { jsapiScript: 'https://5b7e0a19c3d8.us-east-1.captcha-sdk.awswaf.com/5b7e0a19c3d8/jsapi.js' },
+);
+
+result.captcha_voucher, result.existing_token;
+```
+
+`iv` and `context` are optional and travel together: send both or neither. Left
+out, CapSkip reads them from the page at solve time, which is the safer choice
+when your copy of the page is more than a few minutes old.
+
+The answer is not a token. POST `captcha_voucher` and `existing_token` as JSON
+to the `voucher` endpoint beside the page's `challenge.js`; the response's
+`token` is the `aws-waf-token` cookie. The pair is short-lived, so exchange it
+immediately rather than storing it.
+
+Every script URL (`challenge_script`, `captcha_script`, `jsapiScript`) must be an
+https URL on an `awswaf.com` host. CapSkip posts the solution to the host the
+script names, so anything else is refused before the request is made. See the
+[AWS WAF API docs](https://capskip.com/api-docs/#aws-waf).
+
+### With a proxy (every method except image captcha)
 
 ```js
 // Proxy is not supported for image captcha
@@ -325,7 +452,11 @@ Every solve method resolves to:
 ```
 
 GeeTest additionally expands its answer into `challenge`, `validate`, and
-`seccode`, while `code` keeps the raw JSON string. ALTCHA adds `token` (the same
+`seccode`, while `code` keeps the raw JSON string. CaptchaFox and Friendly
+Captcha add `token`, the same string as `code`. Capy expands its answer into
+`captchakey`, `challengekey` and `answer` — it returns an object rather than a
+token, and `code` keeps the raw answer. AWS WAF likewise returns an object,
+expanded into `captcha_voucher` and `existing_token`. ALTCHA adds `token` (the same
 string as `code`) and `number`, the counter that solved it.
 
 ---
@@ -371,7 +502,7 @@ const result: SolveResult = await solver.recaptcha('...', 'https://example.com')
 
 ### How do I solve a captcha in Node.js?
 
-Install the CapSkip desktop app, `npm install capskip`, then call the method that matches the widget — `recaptcha()`, `turnstile()`, `geetest()`, `altcha()` or `normal()`. Each returns a Promise that resolves once CapSkip has an answer, giving you a token, or the recognized text in the case of an image captcha.
+Install the CapSkip desktop app, `npm install capskip`, then call the method that matches the widget — `recaptcha()`, `turnstile()`, `geetest()`, `altcha()`, `capy()`, `captchafox()`, `friendlyCaptcha()`, `amazonWaf()` or `normal()`. Each returns a Promise that resolves once CapSkip has an answer, giving you a token, or the recognized text in the case of an image captcha.
 
 ### Is this a free captcha solver?
 
@@ -379,7 +510,7 @@ The SDK itself is MIT-licensed and free. Solving needs the CapSkip app, which is
 
 ### Which captchas can it solve?
 
-reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, ALTCHA, and image/text captchas. Not hCaptcha, and not FunCaptcha/Arkose.
+reCAPTCHA v2 (checkbox and invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF, and image/text captchas. Not hCaptcha, and not FunCaptcha/Arkose.
 
 ### Does it work with Puppeteer and Playwright?