capskip 1.0.2 → 1.2.0

package/src/solver.js

@@ -83,12 +83,140 @@ function applyPollResult(result, polled) {
     if (userAgent) {
       result.userAgent = userAgent;
     }
+    // ALTCHA's createTask-shaped `solution` object. Carried through so
+    // applyAltchaSolution can read the counter the server already worked out,
+    // which is the only reliable source for a proof-of-work v2 answer; that
+    // function deletes it, so it never reaches the caller.
+    if (polled.solution !== null && typeof polled.solution === 'object') {
+      result.solution = polled.solution;
+    }
   } else {
     result.code = polled;
   }
   return result;
 }
 
+// GeeTest answers come back as a JSON string in `request`, keyed with the
+// geetest_ prefix that the target site's own form fields use.
+const GEETEST_FIELDS = [
+  ['challenge', 'geetest_challenge'],
+  ['validate', 'geetest_validate'],
+  ['seccode', 'geetest_seccode'],
+];
+
+/**
+ * Expand the GeeTest answer into `challenge` / `validate` / `seccode`.
+ *
+ * `code` keeps the raw JSON string so callers that forward it verbatim (or that
+ * were written against another solver's API) keep working. If it does not parse,
+ * the result is returned untouched rather than masking the server's reply.
+ */
+function applyGeetestSolution(result) {
+  let payload;
+  try {
+    payload = JSON.parse(result.code || '');
+  } catch (err) {
+    return result;
+  }
+
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    return result;
+  }
+
+  for (const [short, prefixed] of GEETEST_FIELDS) {
+    const value = payload[prefixed] !== undefined ? payload[prefixed] : payload[short];
+    if (value !== undefined && value !== null) {
+      result[short] = value;
+    }
+  }
+
+  return result;
+}
+
+// ALTCHA answers come back as a base64 payload: the challenge document with the
+// winning counter added. That payload is what the site's own `altcha` form field
+// carries, so it is posted back verbatim.
+
+/**
+ * Expose the answer as `token`, and the winning counter as `number`.
+ *
+ * `code` keeps the raw answer so callers that forward it verbatim (or that were
+ * written against another solver's API) keep working; `token` is the same string,
+ * named for the form field it goes into. If the payload does not decode, the
+ * result is returned untouched rather than masking the server's reply.
+ */
+/**
+ * Dig the winning counter out of a token, whichever scheme produced it.
+ *
+ * The two ALTCHA generations nest it differently: a legacy payload is the
+ * challenge document with a top-level `number` added, while a proof-of-work v2
+ * payload is `{ challenge: {...}, solution: { counter: N, ... } }` and has no
+ * `number` at all. Returns undefined if the payload does not decode.
+ */
+function tokenCounter(code) {
+  let payload;
+  try {
+    const decoded = Buffer.from(code, 'base64');
+    // Buffer.from is lenient: it drops invalid characters instead of throwing,
+    // so round-trip to confirm the input really was base64 before trusting it.
+    if (decoded.toString('base64').replace(/=+$/, '') !== code.replace(/=+$/, '')) {
+      return undefined;
+    }
+    payload = JSON.parse(decoded.toString('utf8'));
+  } catch (err) {
+    return undefined;
+  }
+
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    return undefined;
+  }
+
+  if (payload.number !== undefined) {
+    return payload.number;
+  }
+
+  if (payload.solution !== null && typeof payload.solution === 'object') {
+    return payload.solution.counter;
+  }
+
+  return undefined;
+}
+
+/**
+ * Expose the answer as `token`, and the winning counter as `number`.
+ *
+ * `code` keeps the raw answer so callers that forward it verbatim (or that were
+ * written against another solver's API) keep working; `token` is the same
+ * string, named for the form field it goes into.
+ *
+ * The counter comes from the server's own `solution` object when the poll
+ * carried one, because that is the single field both ALTCHA generations report
+ * the same way. Only if it is absent — a plain-text poll — is it dug out of the
+ * token, which is shaped differently per scheme. If neither yields one, the
+ * result keeps its token and simply has no `number`, rather than masking the
+ * server's reply.
+ */
+function applyAltchaSolution(result) {
+  const code = result.code || '';
+  result.token = code;
+
+  const { solution } = result;
+  delete result.solution;
+
+  let number = solution !== null && typeof solution === 'object'
+    ? solution.number
+    : undefined;
+  if (number === undefined) {
+    number = tokenCounter(code);
+  }
+
+  if (number !== undefined) {
+    result.number = number;
+  }
+
+  return result;
+}
+
 // CapSkip's in.php returns OK|<id> by default, or {"status":1,"request":"<id>"}
 // when the submit carried json=1. Accept both so submitting with json=1 works.
 function parseSubmitResponse(response) {
@@ -112,7 +240,7 @@ function parseSubmitResponse(response) {
   throw new ApiException(`cannot recognize response ${response}`);
 }
 
-/** Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile). */
+/** Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile, GeeTest v3, ALTCHA). */
 class CapSkip {
   constructor({
     apiKey = 'capskip',
@@ -167,6 +295,70 @@ class CapSkip {
     });
   }
 
+  /**
+   * Solve a GeeTest v3 slider.
+   *
+   * `gt` is static per site; `challenge` is single-use and expires in about a
+   * minute, so fetch a fresh pair immediately before calling this. Pass
+   * `api_server` when the site uses a non-default GeeTest API server domain.
+   *
+   * The result carries the raw answer as `code` (a JSON string) plus the parsed
+   * `challenge`, `validate`, and `seccode` fields to post back to the target site.
+   */
+  async geetest(gt, challenge, url, options = {}) {
+    // Like reCAPTCHA, this is a real browser solve (load, slide, verify) and can
+    // retry internally, 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,
+      gt,
+      challenge,
+      url,
+      ...options,
+      method: 'geetest',
+      poll_json: 1,
+    });
+    return applyGeetestSolution(result);
+  }
+
+  /**
+   * Solve an ALTCHA proof-of-work challenge.
+   *
+   * Pass `challengeUrl` for CapSkip to fetch the challenge itself, or
+   * `challengeJson` with the document you already have (a JSON string, or an
+   * object which is serialized for you). Sending both is allowed -- the inline
+   * document wins. A proxy applies only to the `challengeUrl` fetch.
+   *
+   * Challenges expire fast -- some sites inside two minutes -- and an expired one
+   * is refused with a bare "verification failed" that looks exactly like a wrong
+   * answer. Fetch the challenge immediately before calling, and post the token
+   * promptly.
+   *
+   * The result carries the raw answer as `code`, the same string as `token`
+   * (what the site's `altcha` form field expects, verbatim), and the counter
+   * that solved it as `number`.
+   */
+  async altcha(url, options = {}) {
+    // An unset challenge param is dropped rather than sent as undefined, so
+    // `altcha(url, { challengeUrl, challengeJson })` works with either left out.
+    const given = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    }
+
+    // Unlike GeeTest and reCAPTCHA this is CPU proof-of-work measured in
+    // milliseconds, not a browser solve, so it keeps the default timeout.
+    const result = await this.solve({
+      url,
+      ...given,
+      method: 'altcha',
+      poll_json: 1,
+    });
+    return applyAltchaSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -252,6 +444,12 @@ class CapSkip {
     if (method === 'turnstile') {
       return prepareSubmitParams(params, 'turnstile');
     }
+    if (method === 'geetest') {
+      return prepareSubmitParams(params, 'geetest');
+    }
+    if (method === 'altcha') {
+      return prepareSubmitParams(params, 'altcha');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -263,4 +461,6 @@ module.exports = {
   parsePollResponse,
   parseSubmitResponse,
   applyPollResult,
+  applyGeetestSolution,
+  applyAltchaSolution,
 };

package/types/index.d.ts

@@ -1,6 +1,6 @@
 // Type definitions for the CapSkip Node.js SDK.
 
-/** Proxy passed to reCAPTCHA / Turnstile solves. */
+/** Proxy passed to reCAPTCHA / Turnstile / GeeTest solves. */
 export interface Proxy {
   /** Proxy type: `HTTP`, `HTTPS`, `SOCKS5`, or `SOCKS5H`. */
   type: string;
@@ -18,7 +18,7 @@ export interface CapSkipOptions {
   port?: number;
   /** Seconds to poll an image captcha before timing out. Default `120`. */
   defaultTimeout?: number;
-  /** Seconds to poll reCAPTCHA / Turnstile before timing out. Default `300`. */
+  /** Seconds to poll reCAPTCHA / Turnstile / GeeTest before timing out. Default `300`. */
   recaptchaTimeout?: number;
   /** Max seconds between polls; starts at `0.25` and backs off to this. Default `5`. */
   pollingInterval?: number;
@@ -28,10 +28,28 @@ export interface CapSkipOptions {
 export interface SolveResult {
   /** CapSkip's internal id for this solve. */
   captchaId: string;
-  /** The solution: recognized text for images, a token otherwise. */
+  /**
+   * 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`.
+   */
   code: string;
   /** Turnstile only — the User-Agent to use when submitting the token. */
   userAgent?: string;
+  /** GeeTest only — the `geetest_challenge` value to post back. */
+  challenge?: string;
+  /** GeeTest only — the `geetest_validate` value to post back. */
+  validate?: string;
+  /** GeeTest only — the `geetest_seccode` value to post back. */
+  seccode?: string;
+  /**
+   * ALTCHA only — the base64 payload to post back in the site's `altcha` form
+   * field. The same string as `code`, named for where it goes.
+   */
+  token?: string;
+  /** ALTCHA only — the counter that solved the challenge. */
+  number?: number;
 }
 
 /** Extra options for {@link CapSkip.normal}. */
@@ -84,6 +102,45 @@ export interface TurnstileOptions {
   [key: string]: unknown;
 }
 
+/** Extra options for {@link CapSkip.geetest}. */
+export interface GeetestOptions {
+  /** GeeTest API server domain (alias for `api_server`). */
+  apiServer?: string;
+  /** GeeTest API server domain (alias for `api_server`). */
+  api_subdomain?: string;
+  /** GeeTest API server domain, e.g. `"api-na.geetest.com"`. */
+  api_server?: string;
+  /** `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;
+}
+
+/** Extra options for {@link CapSkip.altcha}. */
+export interface AltchaOptions {
+  /** Endpoint CapSkip fetches the challenge from. */
+  challengeUrl?: string;
+  /** Endpoint CapSkip fetches the challenge from. */
+  challenge_url?: string;
+  /**
+   * The challenge document itself. An object is serialized for you; a string is
+   * sent as-is.
+   */
+  challengeJson?: string | Record<string, unknown>;
+  /** The challenge document itself. */
+  challenge_json?: string | Record<string, unknown>;
+  /** `1` to request the raw JSON response from CapSkip. */
+  json?: number;
+  /** Proxy — used only for the `challengeUrl` fetch, never for the solve. */
+  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). */
@@ -111,6 +168,26 @@ export class CapSkip {
   recaptcha(sitekey: string, url: string, options?: RecaptchaOptions): Promise<SolveResult>;
   /** Solve Cloudflare Turnstile (widget or challenge page). */
   turnstile(sitekey: string, url: string, options?: TurnstileOptions): Promise<SolveResult>;
+  /**
+   * Solve a GeeTest v3 slider.
+   *
+   * `gt` is static per site; `challenge` is single-use and expires in about a
+   * minute, so fetch a fresh pair immediately before calling this.
+   */
+  geetest(
+    gt: string,
+    challenge: string,
+    url: string,
+    options?: GeetestOptions,
+  ): Promise<SolveResult>;
+  /**
+   * Solve an ALTCHA proof-of-work challenge.
+   *
+   * Pass `challengeUrl` for CapSkip to fetch the challenge, or `challengeJson`
+   * with the document itself. Sending both is allowed — the inline document
+   * wins. Challenges expire fast, so fetch one immediately before calling.
+   */
+  altcha(url: string, options?: AltchaOptions): 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. */