capskip 1.1.0 → 1.3.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.1.0",
-  "description": "Node.js SDK for the CapSkip local captcha solver",
+  "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.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "exports": {
@@ -23,10 +23,31 @@
   "keywords": [
     "captcha",
     "captcha-solver",
+    "captcha-solving",
+    "captcha-bypass",
+    "unlimited-captcha-solver",
+    "local-captcha-solver",
+    "free-captcha-solver",
     "recaptcha",
+    "recaptcha-solver",
+    "recaptcha-v2",
+    "recaptcha-v3",
+    "recaptcha-enterprise",
     "cloudflare",
     "turnstile",
+    "turnstile-solver",
+    "cloudflare-turnstile",
     "geetest",
+    "geetest-solver",
+    "image-captcha",
+    "ocr",
+    "2captcha-alternative",
+    "anti-captcha-alternative",
+    "puppeteer",
+    "playwright",
+    "selenium",
+    "browser-automation",
+    "web-scraping",
     "capskip",
     "automation"
   ],

package/src/apiParams.js

@@ -26,6 +26,35 @@ const GEETEST_SUBMIT = new Set([
   'proxy', 'proxytype',
 ]);
 
+const ALTCHA_SUBMIT = new Set([
+  'method', 'pageurl', 'challenge_url', 'challenge_json', 'json',
+  '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',
+]);
+
+// 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.
@@ -39,6 +68,19 @@ const PARAM_ALIASES = {
   data_s: 'data-s',
   apiServer: 'api_server',
   api_subdomain: 'api_server',
+  challengeUrl: 'challenge_url',
+  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',
 };
 
 function has(obj, key) {
@@ -176,6 +218,141 @@ function validateGeetestSubmit(params) {
   }
 }
 
+/**
+ * Drop unset challenge params and serialize an inline challenge document.
+ *
+ * `altcha(url, { challengeUrl, challengeJson })` is normally called with one of
+ * the two left out, and the form body can only carry a string -- so a document
+ * passed as an object is serialized rather than stringified into
+ * "[object Object]". Mirrors the server, which reads a JSON-body `null` as
+ * "not sent".
+ */
+function normalizeAltchaSubmit(params) {
+  const out = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null) {
+      out[key] = value;
+    }
+  }
+
+  const challenge = out.challenge_json;
+  if (typeof challenge === 'object') {
+    out.challenge_json = JSON.stringify(challenge);
+  }
+
+  return out;
+}
+
+function validateAltchaSubmit(params) {
+  if (!params.pageurl) {
+    throw new ValidationException("'pageurl' is required for ALTCHA.");
+  }
+
+  // CapSkip answers ERROR_BAD_PARAMETERS when neither is sent. Sending both is
+  // deliberately allowed -- the inline document simply wins, because fetching
+  // would only re-obtain what the caller already supplied.
+  if (!params.challenge_url && !params.challenge_json) {
+    throw new ValidationException(
+      "ALTCHA needs a challenge: pass 'challenge_url' for CapSkip to fetch it, "
+      + "or 'challenge_json' with the challenge document itself.",
+    );
+  }
+
+  const unknown = unknownKeys(params, ALTCHA_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for ALTCHA: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+/**
+ * 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)}.`,
+    );
+  }
+}
+
 function validateProxyType(params) {
   const proxytype = params.proxytype;
   if (proxytype === undefined || proxytype === null || proxytype === '') {
@@ -201,6 +378,18 @@ function prepareSubmitParams(params, captchaType, version = 'v2') {
     validateTurnstileSubmit(prepared);
   } else if (captchaType === 'geetest') {
     validateGeetestSubmit(prepared);
+  } 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);
   }
 
   // Skipped for 'normal', which rejects proxy outright with a clearer message.
@@ -217,6 +406,12 @@ module.exports = {
   RECAPTCHA_V3_SUBMIT,
   TURNSTILE_SUBMIT,
   GEETEST_SUBMIT,
+  ALTCHA_SUBMIT,
+  CAPY_SUBMIT,
+  CAPTCHAFOX_SUBMIT,
+  FRIENDLY_CAPTCHA_SUBMIT,
+  CAPY_VERSIONS,
+  FRIENDLY_CAPTCHA_VERSIONS,
   PROXY_TYPES,
   PARAM_ALIASES,
   applyParamAliases,
@@ -225,6 +420,12 @@ module.exports = {
   validateRecaptchaSubmit,
   validateTurnstileSubmit,
   validateGeetestSubmit,
+  normalizeAltchaSubmit,
+  validateAltchaSubmit,
+  dropUnset,
+  validateCapySubmit,
+  validateCaptchaFoxSubmit,
+  validateFriendlyCaptchaSubmit,
   validateProxyType,
   prepareSubmitParams,
 };