capskip 1.0.2 → 1.2.0

package/docs/TUTORIAL.md

@@ -12,14 +12,15 @@ Work through it top to bottom, or jump to the section you need.
 5. [reCAPTCHA v2](#5-recaptcha-v2)
 6. [reCAPTCHA v3](#6-recaptcha-v3)
 7. [Cloudflare Turnstile](#7-cloudflare-turnstile)
-8. [Using a proxy](#8-using-a-proxy)
-9. [Concurrency](#9-concurrency)
-10. [The manual workflow](#10-the-manual-workflow)
-11. [Return values](#11-return-values)
-12. [Error handling](#12-error-handling)
-13. [End-to-end: solve and submit](#13-end-to-end-solve-and-submit)
-14. [Parameter reference](#14-parameter-reference)
-15. [Best practices](#15-best-practices)
+8. [GeeTest v3](#8-geetest-v3)
+9. [Using a proxy](#9-using-a-proxy)
+10. [Concurrency](#10-concurrency)
+11. [The manual workflow](#11-the-manual-workflow)
+12. [Return values](#12-return-values)
+13. [Error handling](#13-error-handling)
+14. [End-to-end: solve and submit](#14-end-to-end-solve-and-submit)
+15. [Parameter reference](#15-parameter-reference)
+16. [Best practices](#16-best-practices)
 
 ---
 
@@ -77,7 +78,7 @@ const solver = new CapSkip({
   host: '127.0.0.1',        // where CapSkip is listening
   port: 8080,               // API port from CapSkip settings
   defaultTimeout: 120,      // seconds to wait for an image captcha
-  recaptchaTimeout: 300,    // seconds to wait for reCAPTCHA / Turnstile
+  recaptchaTimeout: 300,    // seconds to wait for reCAPTCHA / Turnstile / GeeTest
   pollingInterval: 5,       // max seconds between result polls (starts at 0.25s, backs off to this)
 });
 ```
@@ -149,7 +150,7 @@ await solver.normal('captcha.png', { json: 1 });
 ```
 
 > **Note:** Proxies are **not** supported for image captcha — passing one throws
-> `ValidationException`. Proxies apply only to reCAPTCHA and Turnstile.
+> `ValidationException`. Proxies apply only to reCAPTCHA, Turnstile, and GeeTest.
 
 ---
 
@@ -231,24 +232,94 @@ await solver.turnstile('0x4AAAAAAA...', 'https://example.com', {
 
 ---
 
-## 8. Using a proxy
+## 8. GeeTest v3
+
+`solver.geetest(gt, challenge, url)` solves the GeeTest v3 slide puzzle.
+
+### Finding `gt` and `challenge`
+
+Unlike a sitekey, GeeTest needs **two** values, and one of them is short-lived:
+
+| Value | Lifetime | Where it comes from |
+|---|---|---|
+| `gt` | Static per site | The same place as `challenge` |
+| `challenge` | **Single-use, expires in ~1 minute** | An endpoint the site calls that returns `{"gt": "...", "challenge": "..."}` |
+
+Open DevTools → Network on the target page and look for a request to something like
+`.../register.php`, `gettype`, or `get.php`. You can also read the values out of the
+`initGeetest({ gt, challenge })` call in the page scripts.
+
+```js
+// Ask the target site for a fresh pair immediately before solving.
+const resp = await fetch('https://example.com/captcha/register.php');
+const { gt, challenge } = await resp.json();
+
+const result = await solver.geetest(gt, challenge, 'https://example.com/login');
+```
+
+### Using the answer
+
+The result carries the three values the site's own front-end would submit:
+
+```js
+result.challenge;   // geetest_challenge
+result.validate;    // geetest_validate
+result.seccode;     // geetest_seccode
+
+result.code;        // the same answer as a raw JSON string
+```
+
+Post them back exactly as the site expects:
+
+```js
+await fetch('https://example.com/login', {
+  method: 'POST',
+  body: new URLSearchParams({
+    username: '...',
+    password: '...',
+    geetest_challenge: result.challenge,
+    geetest_validate: result.validate,
+    geetest_seccode: result.seccode,
+  }),
+});
+```
+
+> **`challenge` is one-shot.** Never cache or reuse a pair. If a solve fails with a
+> bad-challenge error, request a *new* pair and retry — retrying with the same
+> `challenge` can never succeed.
+
+If the site uses a non-default GeeTest API server domain, pass it through:
+
+```js
+await solver.geetest(gt, challenge, url, { api_server: 'api-na.geetest.com' });
+```
+
+Because GeeTest is a real browser solve (load, slide, verify), it uses the longer
+`recaptchaTimeout` budget rather than `defaultTimeout`.
+
+---
+
+## 9. Using a proxy
 
 Solving through the same IP you will submit from greatly improves acceptance rates
-for reCAPTCHA and Turnstile. Pass the proxy as an object with `type` and `uri`:
+for reCAPTCHA, Turnstile, and GeeTest. Pass the proxy as an object with `type` and `uri`:
 
 ```js
 const proxy = { type: 'HTTPS', uri: 'user:pass@1.2.3.4:3128' };
 
 await solver.recaptcha('...', 'https://example.com', { proxy });
 await solver.turnstile('...', 'https://example.com', { proxy });
+await solver.geetest('gt', 'challenge', 'https://example.com', { proxy });
 ```
 
-Supported proxy types: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H`. The `uri` may include
+Supported proxy types: `HTTP`, `HTTPS`, `SOCKS5`, `SOCKS5H` — matched
+case-insensitively. Anything else (including `SOCKS4`) raises
+`ValidationException` before the request is sent. The `uri` may include
 credentials (`login:password@host:port`) or be a bare `host:port`.
 
 ---
 
-## 9. Concurrency
+## 10. Concurrency
 
 Every solve method returns a Promise, so you can solve many captchas concurrently
 with `Promise.all`:
@@ -279,7 +350,7 @@ const results = await Promise.allSettled([task1, task2]);
 
 ---
 
-## 10. The manual workflow
+## 11. The manual workflow
 
 If you want to submit now and collect the answer later, use the two low-level
 steps directly.
@@ -316,7 +387,7 @@ Pass `1` as the second argument to `getResult` to get the full object (including
 
 ---
 
-## 11. Return values
+## 12. Return values
 
 Every high-level solve method (`normal`, `recaptcha`, `turnstile`, `solve`)
 resolves to an object:
@@ -334,7 +405,7 @@ the solution string (or an object when called with `json = 1`).
 
 ---
 
-## 12. Error handling
+## 13. Error handling
 
 The SDK throws four error types, all subclasses of `CapSkipError`:
 
@@ -388,7 +459,7 @@ try {
 
 ---
 
-## 13. End-to-end: solve and submit
+## 14. End-to-end: solve and submit
 
 A realistic flow — solve a reCAPTCHA, then submit the token to the target site
 through the **same** proxy:
@@ -453,7 +524,7 @@ await fetch(CHALLENGE_URL, {
 
 ---
 
-## 14. Parameter reference
+## 15. Parameter reference
 
 ### Solve methods
 
@@ -462,6 +533,7 @@ await fetch(CHALLENGE_URL, {
 | Image | `normal(file, { json })` |
 | reCAPTCHA | `recaptcha(sitekey, url, { version, enterprise, ... })` |
 | Turnstile | `turnstile(sitekey, url, { ... })` |
+| GeeTest v3 | `geetest(gt, challenge, url, { ... })` |
 | Manual submit | `send(params) -> Promise<id>` |
 | Manual poll | `getResult(id, json)` |
 
@@ -474,6 +546,7 @@ The SDK accepts friendly names and converts them to the raw API parameters:
 | `url` | `pageurl` |
 | `score`, `minScore` | `min_score` |
 | `datas`, `data_s` | `data-s` |
+| `apiServer`, `api_subdomain` | `api_server` |
 | `proxy` (object) | `proxy` + `proxytype` strings |
 
 Anything CapSkip does not document for a given captcha type is rejected with
@@ -481,14 +554,17 @@ Anything CapSkip does not document for a given captcha type is rejected with
 
 ---
 
-## 15. Best practices
+## 16. Best practices
 
 - **Keep CapSkip running.** The SDK talks to a local app; if it is not running you
   get `NetworkException`.
 - **Use the token immediately.** reCAPTCHA and Turnstile tokens expire within a
   couple of minutes.
 - **Match sitekey and pageurl exactly** to the page the widget loads on.
-- **Solve and submit from the same IP** (same proxy) for reCAPTCHA and Turnstile.
+- **Fetch a fresh GeeTest `challenge` per solve.** It is single-use and expires in
+  about a minute; a cached pair always fails.
+- **Solve and submit from the same IP** (same proxy) for reCAPTCHA, Turnstile, and
+  GeeTest.
 - **Never commit secrets.** Read `CAPSKIP_API_KEY` and proxy credentials from the
   environment, not source code.
 - **Tune timeouts** for slow captcha types with `recaptchaTimeout` and

package/examples/altcha.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * Solve an ALTCHA proof-of-work challenge.
+ *
+ * ALTCHA is not a recognition captcha -- there is nothing to read. The site
+ * issues a challenge and the browser must brute-force a number that satisfies
+ * it. CapSkip does that work for you, in milliseconds.
+ *
+ * You need the challenge, in one of two forms:
+ *
+ *   * `challengeUrl`  - the endpoint that serves it; CapSkip fetches it for you
+ *   * `challengeJson` - the challenge document itself, if you already have it
+ *
+ * To find them, open DevTools -> Network on the target page and look for the
+ * request the `<altcha-widget>` makes for its challenge (often something like
+ * `/altcha/challenge`). The request URL is your `challengeUrl`; its JSON
+ * response is your `challengeJson`.
+ *
+ * Note the widget attribute that names the endpoint changed between versions:
+ * v1/v2 use `challengeurl="..."`, while v3+ uses `challenge="..."` for both a
+ * URL and inline data. Read the page source rather than assuming.
+ *
+ * Challenges expire fast -- some sites inside two minutes -- so fetch one
+ * immediately before solving and post the token promptly. An expired challenge
+ * is rejected with a bare "verification failed" that looks exactly like a wrong
+ * answer.
+ *
+ * This example issues its own challenge the way a site's server would, so it
+ * runs as-is with no third-party dependency. Swap in your target's endpoint to
+ * use it for real.
+ */
+
+const crypto = require('crypto');
+
+const { CapSkip } = require('../src');
+
+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/signup';
+
+/**
+ * Mint an ALTCHA challenge, exactly as a site's own server would.
+ *
+ * Replace this with a fetch of your target's challenge endpoint -- or skip it
+ * entirely and pass `challengeUrl` so CapSkip does the fetching.
+ */
+function issueChallenge(number = 54321) {
+  const salt = `${crypto.randomBytes(12).toString('hex')}?expires=${
+    Math.floor(Date.now() / 1000) + 600}`;
+  return {
+    algorithm: 'SHA-256',
+    challenge: crypto.createHash('sha256').update(`${salt}${number}`).digest('hex'),
+    salt,
+    signature: '0'.repeat(64),
+    maxnumber: 100000,
+  };
+}
+
+(async () => {
+  // --- Option A: you already have the challenge document ---------------------
+  // No network request at all: CapSkip solves it locally.
+  const result = await solver.altcha(PAGE_URL, { challengeJson: issueChallenge() });
+
+  console.log('Captcha ID:', result.captchaId);
+  console.log('Number:    ', result.number);
+  console.log('Token:     ', `${result.token.slice(0, 60)}...`);
+
+  // --- Option B: let CapSkip fetch the challenge ------------------------------
+  // Point it at the endpoint the widget calls. Add `proxy` if the endpoint
+  // should be fetched from a particular IP -- the proxy is used only for that
+  // fetch, never for the solve itself.
+  //
+  //   const result = await solver.altcha(PAGE_URL, {
+  //     challengeUrl: 'https://example.com/captcha/api/altcha/challenge',
+  //     proxy: { type: 'HTTP', uri: 'login:password@1.2.3.4:8080' },
+  //   });
+
+  // Post the token back in the form field the widget uses, named `altcha`:
+  //
+  //   await fetch(SIGNUP_URL, {
+  //     method: 'POST',
+  //     body: new URLSearchParams({
+  //       email: 'someone@example.com',
+  //       altcha: result.token,
+  //     }),
+  //   });
+  //
+  // Do not re-encode, trim or re-order it. The token is base64 of a JSON
+  // document whose fields are covered by the server's HMAC signature, so any
+  // modification invalidates it.
+
+  // `code` holds the same string as `token`, which is what you forward if you
+  // are porting code written against another solver's API.
+  console.assert(result.code === result.token);
+})().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/geetest.js

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * Solve a GeeTest v3 slider.
+ *
+ * GeeTest v3 needs two values from the target site:
+ *
+ *   - `gt`        static per site
+ *   - `challenge` single-use, expires in about a minute
+ *
+ * The site fetches them itself from an endpoint that returns
+ * `{"gt": "...", "challenge": "..."}` (often `.../register.php` or a
+ * `gettype`/`get.php` request). Open DevTools -> Network to find that request,
+ * then request a *fresh* pair right before solving, as this example does.
+ */
+
+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),
+});
+
+// A public GeeTest v3 demo page, and the endpoint that page calls to issue a
+// fresh gt/challenge pair. Safe to run as-is.
+const PAGE_URL = 'https://2captcha.com/demo/geetest';
+const REGISTER_URL = 'https://2captcha.com/api/v1/captcha-demo/gee-test/init-params';
+
+/** Get a fresh gt/challenge pair. Replace with the endpoint your target uses. */
+async function fetchChallenge() {
+  const resp = await fetch(REGISTER_URL);
+  if (!resp.ok) {
+    throw new Error(`Could not fetch a gt/challenge pair: HTTP ${resp.status}`);
+  }
+  return resp.json();
+}
+
+(async () => {
+  const { gt, challenge } = await fetchChallenge();
+
+  const result = await solver.geetest(gt, challenge, PAGE_URL);
+
+  console.log('Captcha ID:', result.captchaId);
+  console.log('Challenge: ', result.challenge);
+  console.log('Validate:  ', result.validate);
+  console.log('Seccode:   ', result.seccode);
+
+  // `code` holds the same answer as a raw JSON string, which is what you forward
+  // if you are porting code written against another solver's API.
+  console.log('Raw code:  ', result.code);
+
+  // Post these back exactly as the site's own front-end would, e.g.:
+  //
+  //   await fetch(LOGIN_URL, {
+  //     method: 'POST',
+  //     body: new URLSearchParams({
+  //       geetest_challenge: result.challenge,
+  //       geetest_validate:  result.validate,
+  //       geetest_seccode:   result.seccode,
+  //     }),
+  //   });
+  console.log('Form fields:', {
+    geetest_challenge: result.challenge,
+    geetest_validate: result.validate,
+    geetest_seccode: result.seccode,
+  });
+})();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capskip",
-  "version": "1.0.2",
-  "description": "Node.js SDK for the CapSkip local captcha solver",
+  "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.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "exports": {
@@ -23,9 +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

@@ -21,12 +21,33 @@ const TURNSTILE_SUBMIT = new Set([
   'proxy', 'proxytype',
 ]);
 
+const GEETEST_SUBMIT = new Set([
+  'method', 'gt', 'challenge', 'pageurl', 'api_server', 'json',
+  'proxy', 'proxytype',
+]);
+
+const ALTCHA_SUBMIT = new Set([
+  'method', 'pageurl', 'challenge_url', 'challenge_json', 'json',
+  'proxy', 'proxytype',
+]);
+
+// 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.
+const PROXY_TYPES = ['HTTP', 'HTTPS', 'SOCKS5', 'SOCKS5H'];
+
 const PARAM_ALIASES = {
   url: 'pageurl',
   score: 'min_score',
   minScore: 'min_score',
   datas: 'data-s',
   data_s: 'data-s',
+  apiServer: 'api_server',
+  api_subdomain: 'api_server',
+  challengeUrl: 'challenge_url',
+  challengeURL: 'challenge_url',
+  challengeJson: 'challenge_json',
+  challengeJSON: 'challenge_json',
 };
 
 function has(obj, key) {
@@ -145,6 +166,86 @@ function validateTurnstileSubmit(params) {
   }
 }
 
+function validateGeetestSubmit(params) {
+  // All three are documented as required. gt is static per site, challenge is
+  // single-use and expires in about a minute; without them CapSkip 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 ['gt', 'challenge', 'pageurl']) {
+    if (!params[key]) {
+      throw new ValidationException(`'${key}' is required for GeeTest v3.`);
+    }
+  }
+
+  const unknown = unknownKeys(params, GEETEST_SUBMIT);
+  if (unknown.length > 0) {
+    throw new ValidationException(
+      `Unsupported parameters for GeeTest: ${reprList(unknown)}.`,
+    );
+  }
+}
+
+/**
+ * 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)}.`,
+    );
+  }
+}
+
+function validateProxyType(params) {
+  const proxytype = params.proxytype;
+  if (proxytype === undefined || proxytype === null || proxytype === '') {
+    return;
+  }
+  if (!PROXY_TYPES.includes(String(proxytype).toUpperCase())) {
+    throw new ValidationException(
+      `Unsupported proxytype '${proxytype}'. `
+      + `CapSkip accepts: ${PROXY_TYPES.join(', ')}.`,
+    );
+  }
+}
+
 function prepareSubmitParams(params, captchaType, version = 'v2') {
   let prepared = applyParamAliases(params);
   prepared = applyProxy(prepared);
@@ -155,6 +256,16 @@ function prepareSubmitParams(params, captchaType, version = 'v2') {
     validateRecaptchaSubmit(prepared, version);
   } else if (captchaType === 'turnstile') {
     validateTurnstileSubmit(prepared);
+  } else if (captchaType === 'geetest') {
+    validateGeetestSubmit(prepared);
+  } else if (captchaType === 'altcha') {
+    prepared = normalizeAltchaSubmit(prepared);
+    validateAltchaSubmit(prepared);
+  }
+
+  // Skipped for 'normal', which rejects proxy outright with a clearer message.
+  if (captchaType !== 'normal') {
+    validateProxyType(prepared);
   }
 
   return prepared;
@@ -165,11 +276,18 @@ module.exports = {
   RECAPTCHA_V2_SUBMIT,
   RECAPTCHA_V3_SUBMIT,
   TURNSTILE_SUBMIT,
+  GEETEST_SUBMIT,
+  ALTCHA_SUBMIT,
+  PROXY_TYPES,
   PARAM_ALIASES,
   applyParamAliases,
   applyProxy,
   validateNormalSubmit,
   validateRecaptchaSubmit,
   validateTurnstileSubmit,
+  validateGeetestSubmit,
+  normalizeAltchaSubmit,
+  validateAltchaSubmit,
+  validateProxyType,
   prepareSubmitParams,
 };

package/src/index.js

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