capskip 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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

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, Capy Puzzle, CaptchaFox, Friendly Captcha 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()`, `capy()`, `captchafox()`, `friendlyCaptcha()`. 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
 
@@ -38,6 +38,8 @@ This SDK is a thin wrapper over that API, with the method names you would expect
 | **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()`.
 
@@ -135,7 +137,7 @@ const solver = new CapSkip({
   port: 8080,               // CapSkip port from app settings
   defaultTimeout: 120,      // seconds — image captcha polling timeout
   recaptchaTimeout: 300,    // seconds — reCAPTCHA / Turnstile / GeeTest / CaptchaFox /
-                            // Friendly Captcha polling timeout
+                            // 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)
 });
@@ -313,6 +315,48 @@ 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
@@ -411,7 +455,8 @@ GeeTest additionally expands its answer into `challenge`, `validate`, and
 `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. ALTCHA adds `token` (the same
+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.
 
 ---
@@ -457,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()`, `capy()`, `captchafox()`, `friendlyCaptcha()` 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?
 
@@ -465,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, Capy Puzzle, CaptchaFox, Friendly Captcha, 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?
 

package/docs/API_REFERENCE.md

@@ -9,7 +9,7 @@ POST http://<host>:<port>/in.php   → submit captcha
 GET  http://<host>:<port>/res.php  → poll result
 ```
 
-The SDK only supports the four captcha types documented by CapSkip. Every solve
+The SDK only supports the captcha types documented by CapSkip. Every solve
 method returns a `Promise`.
 
 ---
@@ -27,6 +27,7 @@ method returns a `Promise`.
 | Capy Puzzle (slide) | `capy()` | `capy` |
 | CaptchaFox (widget) | `captchafox()` | `captchafox` |
 | Friendly Captcha (proof-of-work) | `friendlyCaptcha()` | `friendly_captcha` |
+| AWS WAF (challenge page or widget) | `amazonWaf()` | `amazon_waf` |
 
 **Proxy** is supported for every method except image captcha. For ALTCHA the
 proxy is used only for the `challengeUrl` fetch; for Capy, only for the
@@ -612,6 +613,106 @@ browser.
 
 ---
 
+## 10. AWS WAF — `amazonWaf(sitekey, url, { ... })`
+
+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`. CapSkip solves both in a real browser. See the
+[CapSkip API docs](https://capskip.com/api-docs/#aws-waf).
+
+### POST `/in.php`
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `key` | string | Yes | CapSkip API key |
+| `method` | string | Yes | `amazon_waf` |
+| `sitekey` | string | Yes | Challenge page: `gokuProps.key`. Widget page: the widget's `apiKey` |
+| `pageurl` | string | Yes | Full http or https URL of the protected page |
+| `iv` | string | No | Challenge page: `gokuProps.iv`. Send together with `context` |
+| `context` | string | No | Challenge page: `gokuProps.context`. Send together with `iv` |
+| `challenge_script` | string | No | Full URL of the page's `challenge.js` |
+| `captcha_script` | string | No | Full URL of the page's `captcha.js` |
+| `jsapiScript` | string | No | Widget page: full URL of `jsapi.js` |
+| `json` | int | No | `0` plain text, `1` JSON |
+| `proxy` | string | No | Proxy address |
+| `proxytype` | string | No | Proxy type |
+
+The SDK also accepts `challengeScript`, `captchaScript` and `jsapi_script`, and
+sends the documented spelling of each. An optional left `undefined`, `null` or
+`''` is not sent — the server reads an empty value as absent.
+
+### Challenge page or widget page
+
+| | Challenge page | Widget page |
+|---|---|---|
+| Recognized by | HTTP 405 with `window.gokuProps` in an inline script | `AwsWafCaptcha.renderCaptcha(container, { apiKey, … })` |
+| `sitekey` | `gokuProps.key` | the widget's `apiKey` |
+| `iv` / `context` | `gokuProps.iv` / `gokuProps.context`, or neither | not sent |
+| Scripts | `challenge_script`, `captcha_script` | `jsapiScript` |
+
+`iv` and `context` come off the same page and only work as a pair, so the SDK
+refuses one without the other. Both are optional: left out, CapSkip reads them
+from `pageurl` at solve time, which is the safer choice when your copy of the
+page is more than a few minutes old.
+
+### Script URLs
+
+CapSkip posts the solution to the host a script URL names, so it refuses any
+script that is not on AWS WAF. The SDK applies the server's rule before the
+request is made: the URL must be `https`, its host must end in `.awswaf.com`, it
+must carry no credentials and no port other than 443, and its path must be one
+or more segments followed by `challenge.js`, `captcha.js` or `jsapi.js`. A query
+string is allowed. Anything else throws `ValidationException`, because CapSkip is
+not an AWS WAF integration for scripts hosted elsewhere.
+
+### GET `/res.php`
+
+The answer is **not a token**. With `json=1` it is an object in `request`:
+
+```json
+{"status":1,"request":{"captcha_voucher":"…","existing_token":"…"}}
+```
+
+and in plain text the same object as one line of JSON after `OK|`. The SDK
+expands it into `captcha_voucher` and `existing_token`; see
+[Return value](#return-value).
+
+### Exchanging the voucher
+
+The two values only work as a pair. POST them as JSON to the `voucher` endpoint
+beside the page's `challenge.js` (the same directory, with `voucher` in place of
+`challenge.js`). The response's `token` is the `aws-waf-token` cookie. Exchange
+them immediately rather than storing them for later.
+
+### SDK usage
+
+```js
+// Challenge page
+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
+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;
+```
+
+Uses `recaptchaTimeout`: a real browser mints the token the voucher is issued
+for, and the puzzle rounds go through AWS on top of that.
+
+---
+
 ## Return value
 
 Every solve method resolves to:
@@ -663,6 +764,19 @@ target form takes (`code` keeps the raw answer):
 }
 ```
 
+AWS WAF returns an object too, expanded into the voucher pair the site's
+`voucher` endpoint trades for the `aws-waf-token` cookie (`code` keeps the raw
+answer):
+
+```js
+{
+  captchaId: '12345',
+  code: { captcha_voucher: '…', existing_token: '…' },
+  captcha_voucher: 'eyJ2b3VjaGVyIjoiRVhBTVBMRSJ9.9QwZcEXAMPLEvoucherJk4LmN0pQ',
+  existing_token: '7d4c2a91-EXAMPLE-4f0b-9e6d-3a1b5c8e2f70:EQoAeXAMPLEtokenAAAA:Wm9wc2E=',
+}
+```
+
 GeeTest additionally expands its answer into `challenge`, `validate`, and
 `seccode` (`code` keeps the raw JSON string):
 
@@ -697,6 +811,9 @@ Convenience aliases mapped before sending to CapSkip:
 | `captchaKey` | `captchakey` |
 | `moduleScript` | `module_script` |
 | `nomoduleScript` / `noModuleScript` | `nomodule_script` |
+| `challengeScript` | `challenge_script` |
+| `captchaScript` | `captcha_script` |
+| `jsapi_script` | `jsapiScript` |
 | `proxy` object | `proxy` + `proxytype` strings |
 
 ```js

package/examples/amazon_waf.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * Solve an AWS WAF CAPTCHA.
+ *
+ * AWS WAF shows up in two forms, and the values you need depend on which one
+ * the target page uses:
+ *
+ *   * A challenge page -- the HTTP 405 interstitial that sets `window.gokuProps`
+ *     in an inline script. `sitekey` is `gokuProps.key`; `iv` and `context` are
+ *     `gokuProps.iv` and `gokuProps.context`. `challenge_script` and
+ *     `captcha_script` are the full URLs of the page's challenge.js and
+ *     captcha.js.
+ *   * A widget page -- an ordinary page that calls
+ *     `AwsWafCaptcha.renderCaptcha(container, { apiKey, ... })`. `sitekey` is
+ *     that `apiKey`, and `jsapiScript` is the full URL of jsapi.js.
+ *
+ * Only `sitekey` and the page URL are required. `iv` and `context` 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.
+ *
+ * Every script URL must be an https URL on an awswaf.com host. CapSkip posts
+ * the solution to the host the script names, so it refuses anything else
+ * before the request is made.
+ *
+ * Unlike reCAPTCHA or Turnstile, the answer is NOT a token you put in a form.
+ * It is a voucher pair that AWS trades for the `aws-waf-token` cookie.
+ */
+
+const { CapSkip } = require('capskip');
+
+const solver = new CapSkip({
+  apiKey: process.env.CAPSKIP_API_KEY || 'capskip',
+  host: process.env.CAPSKIP_HOST || '127.0.0.1',
+  port: Number(process.env.CAPSKIP_PORT || 8080),
+});
+
+const PAGE_URL = 'https://example.com/protected';
+
+// From the challenge page's window.gokuProps.
+const SITEKEY = 'AQIDAHjcYuEXAMPLEghicBgQ/7bFaQZ+m5FKCMDnO+vTbNg96AHDh0IR5vgzHNceHYqZR+GOAAAAfjB8';
+const IV = 'CgAFRDIjfgAAA5yY';
+const CONTEXT = 'Rbp3r8fvbuhmrCqpUe8Mh1TLvs8OSKJZiSs2vCF4dt9rxVZI7xYJa2n5k/9r+XaXe7KUIu2I8nXTDHHkDvIOTDc2';
+const CHALLENGE_JS = 'https://3f2a9c7d41b0.edge.sdk.awswaf.com/3f2a9c7d41b0/8e51d0c7a2f4/challenge.js';
+
+async function main() {
+  const result = await solver.amazonWaf(SITEKEY, PAGE_URL, {
+    iv: IV,
+    context: CONTEXT,
+    challenge_script: CHALLENGE_JS,
+  });
+
+  console.log('Captcha ID:    ', result.captchaId);
+  console.log('Voucher:       ', `${result.captcha_voucher.slice(0, 32)}...`);
+  console.log('Existing token:', `${result.existing_token.slice(0, 32)}...`);
+
+  // --- A widget page -------------------------------------------------------
+  // The widget's apiKey as the sitekey, and the jsapi.js it loads. No iv or
+  // context: a widget page has none.
+  //
+  //   await solver.amazonWaf(
+  //     'Xr9kEXAMPLE2bWQx1vTq8LmZ0aYc4dHs7nFp3gJt6uKw5eRi9AbCdEfGh=_0_1',
+  //     PAGE_URL,
+  //     { jsapiScript: 'https://5b7e0a19c3d8.us-east-1.captcha-sdk.awswaf.com/5b7e0a19c3d8/jsapi.js' },
+  //   );
+  //
+  // --- With a per-request proxy --------------------------------------------
+  //   await solver.amazonWaf(SITEKEY, PAGE_URL, {
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // Exchange the pair for the aws-waf-token cookie: POST both values as JSON
+  // to the `voucher` endpoint that sits beside the page's challenge.js. The
+  // response's `token` is the cookie value. Do this immediately -- the voucher
+  // is short-lived, so do not store the pair for a later request.
+  const voucherUrl = new URL('voucher', CHALLENGE_JS).href;
+  console.log('Voucher URL:   ', voucherUrl);
+  //
+  //   const response = await fetch(voucherUrl, {
+  //     method: 'POST',
+  //     headers: { 'Content-Type': 'application/json' },
+  //     body: JSON.stringify({
+  //       captcha_voucher: result.captcha_voucher,
+  //       existing_token: result.existing_token,
+  //     }),
+  //   });
+  //   const { token } = await response.json();
+  //
+  //   // Then request the protected page with the cookie:
+  //   await fetch(PAGE_URL, { headers: { Cookie: `aws-waf-token=${token}` } });
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capskip",
-  "version": "1.3.0",
-  "description": "Captcha solver for Node.js: solve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest and image captchas with CapSkip, a local unlimited captcha solver with no per-solve fees.",
+  "version": "1.4.0",
+  "description": "Captcha solver for Node.js: solve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest, AWS WAF and image captchas with CapSkip, a local unlimited captcha solver with no per-solve fees.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "exports": {
@@ -39,6 +39,8 @@
     "cloudflare-turnstile",
     "geetest",
     "geetest-solver",
+    "aws-waf",
+    "aws-waf-captcha",
     "image-captcha",
     "ocr",
     "2captcha-alternative",

package/src/apiParams.js

@@ -46,6 +46,19 @@ const FRIENDLY_CAPTCHA_SUBMIT = new Set([
   'api_server', 'useragent', 'json', 'proxy', 'proxytype',
 ]);
 
+const AMAZON_WAF_SUBMIT = new Set([
+  'method', 'sitekey', 'pageurl', 'iv', 'context', 'challenge_script',
+  'captcha_script', 'jsapiScript', 'json', 'proxy', 'proxytype',
+]);
+
+// The script parameters of an AWS WAF task. CapSkip POSTs the solution to the
+// host these name, so it refuses any that is not a genuine AWS WAF one.
+const AMAZON_WAF_SCRIPTS = ['challenge_script', 'captcha_script', 'jsapiScript'];
+
+// The server's own test: one or more [A-Za-z0-9_-] path segments, then one of
+// the three AWS WAF script files.
+const AMAZON_WAF_SCRIPT_PATH = /^(\/[A-Za-z0-9_-]+)+\/(challenge|captcha|jsapi)\.js$/;
+
 // CapSkip solves the puzzle family only. `avatar` is a different challenge
 // behind a different endpoint; the server refuses it at submit time rather than
 // answering it with a puzzle answer, which would bill for a solve the target
@@ -81,6 +94,12 @@ const PARAM_ALIASES = {
   moduleScript: 'module_script',
   nomoduleScript: 'nomodule_script',
   noModuleScript: 'nomodule_script',
+  // AWS WAF: the API documents challenge_script / captcha_script in snake case
+  // and jsapiScript in camel case, as 2Captcha does. Accept the other spelling
+  // of each, which is what createTask-style callers arrive with.
+  challengeScript: 'challenge_script',
+  captchaScript: 'captcha_script',
+  jsapi_script: 'jsapiScript',
 };
 
 function has(obj, key) {
@@ -353,6 +372,90 @@ function validateFriendlyCaptchaSubmit(params) {
   }
 }
 
+/**
+ * True for a script URL CapSkip will accept on an AWS WAF task.
+ *
+ * Mirrors the server: https, a host under .awswaf.com, no credentials or
+ * explicit port, and a path ending in challenge.js, captcha.js or jsapi.js.
+ * The server only applies the check once the task is queued, so failing here
+ * saves a submit that could never solve.
+ */
+function isAmazonWafScriptUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(String(url).trim());
+  } catch (error) {
+    return false;
+  }
+  // WHATWG URL already lowercases the scheme and host, and drops a :443 on an
+  // https URL, so `port` is empty for both the default and an explicit 443.
+  return parsed.protocol === 'https:'
+    && parsed.hostname.toLowerCase().endsWith('.awswaf.com')
+    && parsed.username === ''
+    && parsed.password === ''
+    && (parsed.port === '' || parsed.port === '443')
+    && AMAZON_WAF_SCRIPT_PATH.test(parsed.pathname);
+}
+
+/**
+ * Drop unset optionals, and the empty ones too: an AWS WAF optional left as ''
+ * means "not sent" to the server, exactly like an absent one, so it is dropped
+ * rather than tripping the iv/context pairing.
+ */
+function normalizeAmazonWafSubmit(params) {
+  const out = {};
+  for (const [key, value] of Object.entries(dropUnset(params))) {
+    if (value !== '') {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function validateAmazonWafSubmit(params) {
+  // Without sitekey the server answers ERROR_BAD_PARAMETERS and without
+  // pageurl ERROR_PAGEURL. Fail locally so a missing value costs no round-trip.
+  for (const key of ['sitekey', 'pageurl']) {
+    if (!params[key]) {
+      throw new ValidationException(`'${key}' is required for Amazon WAF.`);
+    }
+  }
+
+  const pageurl = String(params.pageurl).trim();
+  if (!/^https?:\/\//i.test(pageurl)) {
+    throw new ValidationException(
+      `'pageurl' must be a full http or https URL for Amazon WAF, got '${pageurl}'.`,
+    );
+  }
+
+  // iv and context come off the same challenge page and only work as a pair;
+  // the server refuses one without the other with ERROR_BAD_PARAMETERS.
+  if (Boolean(params.iv) !== Boolean(params.context)) {
+    throw new ValidationException(
+      "Amazon WAF 'iv' and 'context' go together: send both (a challenge "
+      + 'page) or neither (a widget page, or let CapSkip read them from pageurl).',
+    );
+  }
+
+  for (const key of AMAZON_WAF_SCRIPTS) {
+    const value = params[key];
+    if (value && !isAmazonWafScriptUrl(value)) {
+      throw new ValidationException(
+        `'${key}' must be the https URL of an AWS WAF script on an awswaf.com `
+        + `host (challenge.js, captcha.js or jsapi.js), got '${value}'. CapSkip `
+        + 'refuses any other script, because it is not an AWS WAF integration.',
+      );
+    }
+  }
+
+  const unknown = unknownKeys(params, AMAZON_WAF_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for Amazon WAF: ${reprList(unknown)}.`,
+    );
+  }
+}
+
 function validateProxyType(params) {
   const proxytype = params.proxytype;
   if (proxytype === undefined || proxytype === null || proxytype === '') {
@@ -390,6 +493,9 @@ function prepareSubmitParams(params, captchaType, version = 'v2') {
   } else if (captchaType === 'friendly_captcha') {
     prepared = dropUnset(prepared);
     validateFriendlyCaptchaSubmit(prepared);
+  } else if (captchaType === 'amazon_waf') {
+    prepared = normalizeAmazonWafSubmit(prepared);
+    validateAmazonWafSubmit(prepared);
   }
 
   // Skipped for 'normal', which rejects proxy outright with a clearer message.
@@ -410,6 +516,8 @@ module.exports = {
   CAPY_SUBMIT,
   CAPTCHAFOX_SUBMIT,
   FRIENDLY_CAPTCHA_SUBMIT,
+  AMAZON_WAF_SUBMIT,
+  AMAZON_WAF_SCRIPTS,
   CAPY_VERSIONS,
   FRIENDLY_CAPTCHA_VERSIONS,
   PROXY_TYPES,
@@ -426,6 +534,9 @@ module.exports = {
   validateCapySubmit,
   validateCaptchaFoxSubmit,
   validateFriendlyCaptchaSubmit,
+  isAmazonWafScriptUrl,
+  normalizeAmazonWafSubmit,
+  validateAmazonWafSubmit,
   validateProxyType,
   prepareSubmitParams,
 };

package/src/index.js

@@ -27,5 +27,5 @@ module.exports = {
   NetworkException,
   ApiException,
   TimeoutException,
-  version: '1.1.0',
+  version: '1.4.0',
 };

package/src/solver.js

@@ -222,7 +222,7 @@ function applyAltchaSolution(result) {
 const CAPY_FIELDS = ['captchakey', 'challengekey', 'answer', 'respKey'];
 
 /**
- * Expand the Capy answer into `captchakey` / `challengekey` / `answer`.
+ * Copy `fields` out of an answer that is an object rather than a token.
  *
  * `code` keeps the raw answer -- an object when polled with json=1, where the
  * server puts it straight into `request`, or the JSON string it sends after
@@ -232,7 +232,7 @@ const CAPY_FIELDS = ['captchakey', 'challengekey', 'answer', 'respKey'];
  * If the answer does not parse, the result is returned untouched rather than
  * masking the server's reply.
  */
-function applyCapySolution(result) {
+function expandObjectAnswer(result, fields) {
   let payload = result.solution;
   delete result.solution;
 
@@ -253,7 +253,7 @@ function applyCapySolution(result) {
     return result;
   }
 
-  for (const field of CAPY_FIELDS) {
+  for (const field of fields) {
     if (Object.prototype.hasOwnProperty.call(payload, field)) {
       result[field] = payload[field];
     }
@@ -262,6 +262,21 @@ function applyCapySolution(result) {
   return result;
 }
 
+/** Expand the Capy answer into `captchakey` / `challengekey` / `answer`. */
+function applyCapySolution(result) {
+  return expandObjectAnswer(result, CAPY_FIELDS);
+}
+
+// An AWS WAF solution is two values that only work as a pair: the voucher AWS
+// issued for the answered puzzle, and the token it was issued for. The site's
+// own /voucher endpoint trades them for the aws-waf-token cookie.
+const AMAZON_WAF_FIELDS = ['captcha_voucher', 'existing_token'];
+
+/** Expand the AWS WAF answer into `captcha_voucher` / `existing_token`. */
+function applyAmazonWafSolution(result) {
+  return expandObjectAnswer(result, AMAZON_WAF_FIELDS);
+}
+
 /**
  * Expose a single-token answer as `token`, named for the form field it fills.
  *
@@ -309,7 +324,10 @@ function parseSubmitResponse(response) {
   throw new ApiException(`cannot recognize response ${response}`);
 }
 
-/** Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile, GeeTest v3, ALTCHA). */
+/**
+ * Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile,
+ * GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF).
+ */
 class CapSkip {
   constructor({
     apiKey = 'capskip',
@@ -553,6 +571,55 @@ class CapSkip {
     return applyTokenSolution(result);
   }
 
+  /**
+   * Solve an AWS WAF (Amazon WAF) CAPTCHA.
+   *
+   * Only `sitekey` and `url` are required:
+   *
+   * - On a challenge page (the HTTP 405 page with `window.gokuProps`), `sitekey`
+   *   is `gokuProps.key`, and `iv` and `context` are `gokuProps.iv` and
+   *   `gokuProps.context`. Send both or neither -- left out, CapSkip reads them
+   *   from `url` at solve time, which is the safer choice when your copy of the
+   *   page is more than a few minutes old. `challenge_script` and
+   *   `captcha_script` are the full URLs of the page's challenge.js and
+   *   captcha.js.
+   * - On a widget page (`AwsWafCaptcha.renderCaptcha`), `sitekey` is the
+   *   widget's `apiKey`; pass `jsapiScript` with the full URL of jsapi.js and no
+   *   `iv` / `context`.
+   *
+   * Every script URL must be an https URL on an awswaf.com host; anything else
+   * is refused before the request is sent.
+   *
+   * The result carries `captcha_voucher` and `existing_token`, plus the raw
+   * answer as `code`. The two only work as a pair: POST them as JSON to the
+   * `voucher` endpoint next to the page's challenge.js and the response's
+   * `token` is the aws-waf-token cookie. Exchange them as soon as they arrive
+   * rather than storing them for later.
+   */
+  async amazonWaf(sitekey, url, options = {}) {
+    // An unset optional is dropped rather than sent as undefined; an empty one
+    // is dropped during validation, since the server reads '' as "not sent".
+    const given = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    }
+
+    // A real browser mints the token the voucher is issued for, and the puzzle
+    // rounds go through AWS on top of that, so it gets the longer of the two
+    // timeouts unless the caller asked for a specific one.
+    const result = await this.solve({
+      timeout: this.recaptchaTimeout,
+      sitekey,
+      url,
+      ...given,
+      method: 'amazon_waf',
+      poll_json: 1,
+    });
+    return applyAmazonWafSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -653,6 +720,9 @@ class CapSkip {
     if (method === 'friendly_captcha') {
       return prepareSubmitParams(params, 'friendly_captcha');
     }
+    if (method === 'amazon_waf') {
+      return prepareSubmitParams(params, 'amazon_waf');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -667,5 +737,7 @@ module.exports = {
   applyGeetestSolution,
   applyAltchaSolution,
   applyCapySolution,
+  applyAmazonWafSolution,
+  expandObjectAnswer,
   applyTokenSolution,
 };

package/types/index.d.ts

@@ -20,7 +20,7 @@ export interface CapSkipOptions {
   defaultTimeout?: number;
   /**
    * Seconds to poll reCAPTCHA / Turnstile / GeeTest / CaptchaFox / Friendly
-   * Captcha before timing out. Default `300`. ALTCHA and Capy use
+   * Captcha / AWS WAF before timing out. Default `300`. ALTCHA and Capy use
    * `defaultTimeout` instead — neither is a browser solve.
    */
   recaptchaTimeout?: number;
@@ -36,8 +36,8 @@ export interface SolveResult {
    * The solution: recognized text for images, a token otherwise. For GeeTest
    * this is the raw JSON string CapSkip returns — prefer the parsed
    * `challenge` / `validate` / `seccode` fields below. For ALTCHA it is the
-   * base64 token, also exposed as `token`. For Capy it is the raw answer
-   * object, expanded into the three fields below.
+   * base64 token, also exposed as `token`. For Capy and AWS WAF it is the raw
+   * answer object, expanded into the fields below.
    */
   code: string | Record<string, unknown>;
   /**
@@ -73,6 +73,15 @@ export interface SolveResult {
    * 2Captcha's documented response; it carries nothing.
    */
   respKey?: string;
+  /**
+   * AWS WAF only — the voucher AWS issued for the answered puzzle. Only valid
+   * together with `existing_token`: POST both as JSON to the `voucher` endpoint
+   * beside the page's challenge.js, whose response `token` is the
+   * `aws-waf-token` cookie. Exchange immediately.
+   */
+  captcha_voucher?: string;
+  /** AWS WAF only — the token the voucher was issued for. Pair with `captcha_voucher`. */
+  existing_token?: string;
 }
 
 /** Extra options for {@link CapSkip.normal}. */
@@ -239,6 +248,38 @@ export interface FriendlyCaptchaOptions {
   [key: string]: unknown;
 }
 
+/** Extra options for {@link CapSkip.amazonWaf}. */
+export interface AmazonWafOptions {
+  /**
+   * Challenge page: `gokuProps.iv`. Send together with `context`, or leave both
+   * out and CapSkip reads them from the page at solve time.
+   */
+  iv?: string;
+  /** Challenge page: `gokuProps.context`. Send together with `iv`. */
+  context?: string;
+  /** Full https URL of the page's `challenge.js` on an `awswaf.com` host. */
+  challenge_script?: string;
+  /** Full https URL of the page's `challenge.js` (alias for `challenge_script`). */
+  challengeScript?: string;
+  /** Full https URL of the page's `captcha.js` on an `awswaf.com` host. */
+  captcha_script?: string;
+  /** Full https URL of the page's `captcha.js` (alias for `captcha_script`). */
+  captchaScript?: string;
+  /** Widget page: full https URL of `jsapi.js` on an `awswaf.com` host. */
+  jsapiScript?: string;
+  /** Widget page: full https URL of `jsapi.js` (alias for `jsapiScript`). */
+  jsapi_script?: string;
+  /** Poll timeout in seconds. Default: the client's `recaptchaTimeout`. */
+  timeout?: number;
+  /** `1` to request the raw JSON response from CapSkip. */
+  json?: number;
+  /** Proxy used for solving. */
+  proxy?: Proxy | string;
+  /** Proxy type when `proxy` is a bare string. */
+  proxytype?: string;
+  [key: string]: unknown;
+}
+
 /** Options for the {@link CapSkip.solve} manual workflow. */
 export interface SolveOptions {
   /** Poll timeout in seconds (falls back to the configured default). */
@@ -320,6 +361,21 @@ export class CapSkip {
     url: string,
     options?: FriendlyCaptchaOptions,
   ): Promise<SolveResult>;
+  /**
+   * Solve an AWS WAF CAPTCHA.
+   *
+   * On a challenge page, `sitekey` is `gokuProps.key` and `iv` / `context` are
+   * `gokuProps.iv` / `gokuProps.context` (both or neither). On a widget page,
+   * `sitekey` is the widget's `apiKey`; pass `jsapiScript`. Script URLs must be
+   * https on an `awswaf.com` host. The result carries `captcha_voucher` and
+   * `existing_token`, which the site's `voucher` endpoint trades for the
+   * `aws-waf-token` cookie.
+   */
+  amazonWaf(
+    sitekey: string,
+    url: string,
+    options?: AmazonWafOptions,
+  ): Promise<SolveResult>;
   /** Submit then poll to completion. Used by the higher-level solve methods. */
   solve(options?: SolveOptions): Promise<SolveResult>;
   /** Submit a captcha without polling; resolves to the captcha id. */