capskip 1.2.0 → 1.4.0

package/examples/capy.js

@@ -0,0 +1,101 @@
+'use strict';
+
+/**
+ * Solve a Capy Puzzle captcha.
+ *
+ * Capy is a slide puzzle: a piece has to be dragged into the hole cut out of a
+ * photograph. CapSkip locates the hole and produces the drag path, which takes
+ * one HTTP fetch and about a tenth of a second of pixel math -- no browser.
+ *
+ * You need two values, both read off the target page:
+ *
+ *   * captchakey - the site's public Capy key, prefixed `PUZZLE_`. Look for
+ *     `capy_captchakey` in the page source, or read it out of the widget script
+ *     URL: <script src="https://jp.api.capy.me/puzzle/get_js/?k=PUZZLE_XXXX">
+ *   * pageurl    - the full URL of the page the captcha is on
+ *
+ * Optionally `api_server`, the root of the Capy API the key lives behind, taken
+ * from that same script URL. CapSkip defaults to https://jp.api.capy.me.
+ * Note that api.capy.me no longer resolves, although several solver services
+ * still document it -- if a site's widget points elsewhere, pass that.
+ *
+ * Unlike reCAPTCHA or Turnstile, the answer is NOT a single token. It is three
+ * values that together go into the target form, and all three must be submitted.
+ */
+
+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 CAPTCHA_KEY = 'PUZZLE_Abc1dEFghIJKLM2no34P56q7rStu8v';
+const PAGE_URL = 'https://example.com/login';
+
+async function main() {
+  const result = await solver.capy(CAPTCHA_KEY, PAGE_URL);
+
+  console.log('Captcha ID:   ', result.captchaId);
+  console.log('Captcha key:  ', result.captchakey);
+  console.log('Challenge key:', result.challengekey);
+  console.log('Answer:       ', `${result.answer.slice(0, 48)}...`);
+
+  // --- With a non-default API server ---------------------------------------
+  //
+  //   await solver.capy(CAPTCHA_KEY, PAGE_URL, {
+  //     api_server: 'https://jp.api.capy.me/',
+  //   });
+  //
+  // --- With a per-request proxy --------------------------------------------
+  // The proxy is used for the puzzle-image fetch, which is the only request a
+  // Capy solve makes. Worth configuring once you solve at any volume: a steady
+  // stream of puzzle draws from one address is the pattern rate limiting exists
+  // to catch.
+  //
+  //   await solver.capy(CAPTCHA_KEY, PAGE_URL, {
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // Post all three values back in the fields the Capy widget would have filled
+  // in. Submit them verbatim -- `answer` is the drag path the widget would have
+  // recorded, and the site's backend verifies it against the challenge it
+  // issued, so trimming or re-encoding it invalidates the solve.
+  //
+  //   await fetch(LOGIN_URL, {
+  //     method: 'POST',
+  //     body: new URLSearchParams({
+  //       email: 'someone@example.com',
+  //       capy_captchakey: result.captchakey,
+  //       capy_challengekey: result.challengekey,
+  //       capy_answer: result.answer,
+  //     }),
+  //   });
+  console.log('Form fields:', {
+    capy_captchakey: result.captchakey,
+    capy_challengekey: result.challengekey,
+    capy_answer: `${result.answer.slice(0, 32)}...`,
+  });
+
+  // The challenge key is single-use and short-lived: CapSkip generates it at
+  // solve time and the puzzle is bound to it. Submit promptly rather than
+  // caching these values or reusing a challengekey for a second submission.
+  //
+  // One more thing worth knowing if you ever build against Capy yourself: it
+  // grades the wall-clock gap between issuing the puzzle and verifying the
+  // answer, and refuses anything superhuman with "CAPTCHA verification failed"
+  // -- the same message a wrong answer gets. CapSkip therefore holds every
+  // result until two seconds have elapsed, so a solve takes about that long
+  // rather than a fifth of a second. Nothing to configure; just do not be
+  // surprised by the latency.
+
+  // `respKey` comes back empty for a puzzle solve. It exists for shape
+  // compatibility with 2Captcha's documented response and carries nothing.
+  console.log('respKey is empty:', result.respKey === '');
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});

package/examples/friendly_captcha.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Solve a Friendly Captcha proof-of-work challenge.
+ *
+ * Friendly Captcha asks the visitor's browser to do a piece of arithmetic
+ * instead of asking the visitor to do anything: there is no image, no slider and
+ * no audio fallback. CapSkip does that work and returns the token the widget
+ * would have written into your form.
+ *
+ * You need two values, and a third is worth sending whenever you can get it:
+ *
+ *   * sitekey      - the `data-sitekey` attribute of the widget element, which
+ *                    is the one carrying class="frc-captcha"
+ *   * pageurl      - the full URL of the page the widget appears on
+ *   * moduleScript - the `src` of the widget script tag carrying type="module".
+ *                    Not required, but it is what tells CapSkip which protocol
+ *                    version the site uses.
+ *
+ * READ THE VERSION SECTION BELOW. It is the part that will cost you an afternoon
+ * if you skip it.
+ */
+
+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 SITEKEY = 'FCMGEMUD2M567T8G';
+const PAGE_URL = 'https://example.com/signup';
+
+async function main() {
+  // --- Version 1 and version 2 ---------------------------------------------
+  // Two entirely different protocols ship under this one name, and a sitekey
+  // does not tell you which one a site uses -- they share a brand and a sitekey
+  // namespace and nothing else. Both are live and both are in use. Solve the
+  // wrong one and you get a well-formed token that the target site rejects, with
+  // no indication anywhere that the version was the problem.
+  //
+  //   v1  friendly-challenge    widget.module.min.js / widget.min.js  (default)
+  //   v2  @friendlycaptcha/sdk  site.min.js
+  //
+  // CapSkip decides in this order: an explicit `version`, then the script URL,
+  // then v1. So either say which version, or send the script URL and let it read
+  // the version off the build the site actually loads.
+
+  // Option A: say which version.
+  const result = await solver.friendlyCaptcha(SITEKEY, PAGE_URL, { version: 'v2' });
+
+  // Option B: let the script URL decide -- the most reliable signal there is.
+  //
+  //   await solver.friendlyCaptcha(SITEKEY, PAGE_URL, {
+  //     moduleScript: 'https://cdn.example.com/@friendlycaptcha/sdk@0.1.6/site.min.js',
+  //     nomoduleScript: 'https://cdn.example.com/@friendlycaptcha/sdk@0.1.6/site.compat.js',
+  //   });
+
+  console.log('Captcha ID:', result.captchaId);
+  console.log('Token:     ', `${result.token.slice(0, 60)}...`);
+  console.log('Length:    ', result.token.length);
+
+  // --- Data residency -------------------------------------------------------
+  // Pass api_server for a sitekey on the EU tenant. Both tenants mint a token
+  // for the same sitekey, so the wrong one is only caught by the site's own
+  // verification -- which is the worst kind of silent.
+  //
+  //   await solver.friendlyCaptcha(SITEKEY, PAGE_URL, { version: 'v2', api_server: 'eu' });
+  //
+  // --- With a per-request proxy --------------------------------------------
+  // You will want one sooner here than almost anywhere else. The service decides
+  // how much work each request is worth and raises that figure for addresses it
+  // has already seen a lot of -- the published range between a fresh address and
+  // a heavily used one is close to thirty times the work for the same token.
+  //
+  //   await solver.friendlyCaptcha(SITEKEY, PAGE_URL, {
+  //     version: 'v2',
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // Post the token back in the hidden field the widget would have filled in.
+  // THE TWO VERSIONS DO NOT USE THE SAME FIELD NAME, which is what catches
+  // people who move a working v1 integration onto a v2 site:
+  //
+  //   v1  ->  frc-captcha-solution
+  //   v2  ->  frc-captcha-response
+  //
+  //   await fetch(SIGNUP_URL, {
+  //     method: 'POST',
+  //     body: new URLSearchParams({
+  //       email: 'someone@example.com',
+  //       'frc-captcha-response': result.token,   // v2
+  //     }),
+  //   });
+  console.log('Form field:', { 'frc-captcha-response': `${result.token.slice(0, 40)}...` });
+
+  // Submit the token verbatim. Do not trim it or re-encode it.
+  //
+  // The two versions produce tokens of very different shapes and sizes: a v1
+  // token is four dot-separated parts and runs to a few hundred characters,
+  // while a v2 token is a single opaque string beginning `AQQA.` and is roughly
+  // six kilobytes long. Make sure whatever carries it -- a hidden field, a
+  // database column, a proxied request -- is sized for that.
+
+  // Solve time is not a constant for this method: the service decides how much
+  // work a request is worth at the moment it is made, so the same sitekey can
+  // cost noticeably more at one time than another. This is why the method uses
+  // recaptchaTimeout rather than the shorter default.
+}
+
+main().catch((error) => {
+  console.error(`${error.name}: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capskip",
-  "version": "1.2.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

@@ -31,6 +31,43 @@ const ALTCHA_SUBMIT = new Set([
   'proxy', 'proxytype',
 ]);
 
+const CAPY_SUBMIT = new Set([
+  'method', 'captchakey', 'pageurl', 'api_server', 'version', 'useragent', 'json',
+  'proxy', 'proxytype',
+]);
+
+const CAPTCHAFOX_SUBMIT = new Set([
+  'method', 'sitekey', 'pageurl', 'api_server', 'useragent', 'json',
+  'proxy', 'proxytype',
+]);
+
+const FRIENDLY_CAPTCHA_SUBMIT = new Set([
+  'method', 'sitekey', 'pageurl', 'version', 'module_script', 'nomodule_script',
+  '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
+// site rejects.
+const CAPY_VERSIONS = ['puzzle'];
+
+// Both spellings the server accepts, and the bare digits it also takes.
+const FRIENDLY_CAPTCHA_VERSIONS = ['v1', 'v2', '1', '2'];
+
 // The only values CapSkip maps to a proxy scheme; it answers
 // ERROR_BAD_PARAMETERS for anything else, SOCKS4 included. Matched
 // case-insensitively, as the server does.
@@ -48,6 +85,21 @@ const PARAM_ALIASES = {
   challengeURL: 'challenge_url',
   challengeJson: 'challenge_json',
   challengeJSON: 'challenge_json',
+  // The server reads userAgent and useragent interchangeably on every method
+  // that takes one, so the SDK settles on the lowercase spelling its parameter
+  // tables document and accepts the camelCase one callers arrive with.
+  userAgent: 'useragent',
+  user_agent: 'useragent',
+  captchaKey: 'captchakey',
+  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) {
@@ -233,6 +285,177 @@ function validateAltchaSubmit(params) {
   }
 }
 
+/**
+ * Drop parameters left unset so an omitted optional is not sent as "undefined".
+ *
+ * The form body can only carry strings, so a default of undefined would
+ * otherwise reach the server stringified. Mirrors the server, which reads a
+ * JSON-body `null` as "not sent".
+ */
+function dropUnset(params) {
+  const out = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function validateCapySubmit(params) {
+  // Both are documented as required; without captchakey the server answers
+  // ERROR_BAD_PARAMETERS and without pageurl ERROR_PAGEURL. Fail locally so a
+  // missing value does not cost a round-trip.
+  for (const key of ['captchakey', 'pageurl']) {
+    if (!params[key]) {
+      throw new ValidationException(`'${key}' is required for Capy.`);
+    }
+  }
+
+  const version = params.version;
+  if (version !== undefined && version !== null && version !== ''
+      && !CAPY_VERSIONS.includes(String(version).toLowerCase())) {
+    throw new ValidationException(
+      `Unsupported Capy version '${version}'. CapSkip solves the puzzle family `
+      + "only -- 'avatar' is a different challenge behind a different endpoint, "
+      + 'and the server refuses it rather than returning a puzzle answer the '
+      + 'target site would reject.',
+    );
+  }
+
+  const unknown = unknownKeys(params, CAPY_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for Capy: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+function validateCaptchaFoxSubmit(params) {
+  for (const key of ['sitekey', 'pageurl']) {
+    if (!params[key]) {
+      throw new ValidationException(`'${key}' is required for CaptchaFox.`);
+    }
+  }
+
+  const unknown = unknownKeys(params, CAPTCHAFOX_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for CaptchaFox: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+function validateFriendlyCaptchaSubmit(params) {
+  for (const key of ['sitekey', 'pageurl']) {
+    if (!params[key]) {
+      throw new ValidationException(`'${key}' is required for Friendly Captcha.`);
+    }
+  }
+
+  const version = params.version;
+  if (version !== undefined && version !== null && version !== ''
+      && !FRIENDLY_CAPTCHA_VERSIONS.includes(String(version).toLowerCase())) {
+    throw new ValidationException(
+      `Unsupported Friendly Captcha version '${version}'. Use 'v1' or 'v2' `
+      + '(a bare 1 or 2 is accepted too). The two are different protocols '
+      + 'sharing one sitekey namespace, so solving the wrong one returns a '
+      + 'well-formed token the target site rejects.',
+    );
+  }
+
+  const unknown = unknownKeys(params, FRIENDLY_CAPTCHA_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for Friendly Captcha: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+/**
+ * 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 === '') {
@@ -261,6 +484,18 @@ function prepareSubmitParams(params, captchaType, version = 'v2') {
   } else if (captchaType === 'altcha') {
     prepared = normalizeAltchaSubmit(prepared);
     validateAltchaSubmit(prepared);
+  } else if (captchaType === 'capy') {
+    prepared = dropUnset(prepared);
+    validateCapySubmit(prepared);
+  } else if (captchaType === 'captchafox') {
+    prepared = dropUnset(prepared);
+    validateCaptchaFoxSubmit(prepared);
+  } 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.
@@ -278,6 +513,13 @@ module.exports = {
   TURNSTILE_SUBMIT,
   GEETEST_SUBMIT,
   ALTCHA_SUBMIT,
+  CAPY_SUBMIT,
+  CAPTCHAFOX_SUBMIT,
+  FRIENDLY_CAPTCHA_SUBMIT,
+  AMAZON_WAF_SUBMIT,
+  AMAZON_WAF_SCRIPTS,
+  CAPY_VERSIONS,
+  FRIENDLY_CAPTCHA_VERSIONS,
   PROXY_TYPES,
   PARAM_ALIASES,
   applyParamAliases,
@@ -288,6 +530,13 @@ module.exports = {
   validateGeetestSubmit,
   normalizeAltchaSubmit,
   validateAltchaSubmit,
+  dropUnset,
+  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',
 };