capskip 1.1.0 → 1.3.0

package/src/solver.js

@@ -83,6 +83,13 @@ 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;
   }
@@ -126,6 +133,159 @@ function applyGeetestSolution(result) {
   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;
+}
+
+// A Capy solution is not a token. It is three values that together go into the
+// target form, under the capy_ prefixed names the widget would have filled in.
+const CAPY_FIELDS = ['captchakey', 'challengekey', 'answer', 'respKey'];
+
+/**
+ * Expand the Capy answer into `captchakey` / `challengekey` / `answer`.
+ *
+ * `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
+ * `OK|` in plain-text mode -- so callers that forward it verbatim (or that were
+ * written against another solver's API) keep working.
+ *
+ * If the answer does not parse, the result is returned untouched rather than
+ * masking the server's reply.
+ */
+function applyCapySolution(result) {
+  let payload = result.solution;
+  delete result.solution;
+
+  if (payload === null || typeof payload !== 'object') {
+    const { code } = result;
+    if (code !== null && typeof code === 'object') {
+      payload = code;
+    } else {
+      try {
+        payload = JSON.parse(code || '');
+      } catch (error) {
+        return result;
+      }
+    }
+  }
+
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    return result;
+  }
+
+  for (const field of CAPY_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(payload, field)) {
+      result[field] = payload[field];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Expose a single-token answer as `token`, named for the form field it fills.
+ *
+ * `code` keeps the raw answer so callers that forward it verbatim keep working;
+ * `token` is the same string. The server's createTask-shaped `solution` object
+ * carries that same string, so it is consumed here rather than handed back as a
+ * second copy -- but it is read first when `request` came through empty, so a
+ * client is never left without the token the poll actually carried.
+ */
+function applyTokenSolution(result) {
+  const { solution } = result;
+  delete result.solution;
+
+  let code = result.code;
+
+  if (!code && solution !== null && typeof solution === 'object') {
+    code = solution.token || '';
+    result.code = code;
+  }
+
+  result.token = code || '';
+  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) {
@@ -149,7 +309,7 @@ function parseSubmitResponse(response) {
   throw new ApiException(`cannot recognize response ${response}`);
 }
 
-/** Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile, GeeTest v3). */
+/** Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile, GeeTest v3, ALTCHA). */
 class CapSkip {
   constructor({
     apiKey = 'capskip',
@@ -230,6 +390,169 @@ class CapSkip {
     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);
+  }
+
+  /**
+   * Solve a Capy Puzzle captcha.
+   *
+   * `sitekey` is the site's public Capy key, conventionally prefixed `PUZZLE_`;
+   * it is sent as the `captchakey` the API documents. Pass `api_server` when the
+   * widget script points somewhere other than `https://jp.api.capy.me`.
+   *
+   * The result is not a token. It carries `captchakey`, `challengekey` and
+   * `answer`, which go into the target form's `capy_captchakey`,
+   * `capy_challengekey` and `capy_answer` fields, plus the raw answer as `code`.
+   * Submit `answer` verbatim -- it is the drag path the widget would have
+   * recorded, so trimming or re-encoding it invalidates the solve.
+   *
+   * The challenge key is single-use and short-lived, so submit promptly rather
+   * than caching the three values for a later request.
+   */
+  async capy(sitekey, url, options = {}) {
+    // An unset optional is dropped rather than sent as undefined, so
+    // `capy(key, url, { apiServer: undefined })` behaves as if it were omitted.
+    const given = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    }
+
+    // A Capy solve is one HTTP fetch plus pixel math, not a browser session, so
+    // it keeps the default timeout. It is held back to roughly two seconds
+    // before the answer is released -- Capy refuses answers that arrive faster
+    // than a human could have produced them -- which the default absorbs.
+    const result = await this.solve({
+      captchakey: sitekey,
+      url,
+      ...given,
+      method: 'capy',
+      poll_json: 1,
+    });
+    return applyCapySolution(result);
+  }
+
+  /**
+   * Solve a CaptchaFox challenge.
+   *
+   * `sitekey` is the public key the widget renders with, conventionally prefixed
+   * `sk_`, and `url` has to be the page the widget actually runs on: CaptchaFox
+   * checks it against the domains the key is registered for and refuses a
+   * mismatch permanently rather than intermittently.
+   *
+   * Pass `api_server` only when the target page does not load the default
+   * widget. A page loading the MAM package expects a `MAM_` prefixed token, and
+   * sending the wrong source still succeeds -- it just returns a token in a
+   * format the site will not accept, which reads as a silent verification
+   * failure rather than an error.
+   *
+   * The result carries the token as both `code` and `token`, for the form's
+   * `cf-captcha-response` field, and `userAgent` when the solve reported one.
+   * That User-Agent is the browser's own, not any you sent, so submit the token
+   * under it.
+   */
+  async captchafox(sitekey, url, options = {}) {
+    const given = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    }
+
+    // A real browser session, like reCAPTCHA and GeeTest, and longer again when
+    // an interactive challenge is drawn -- 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: 'captchafox',
+      poll_json: 1,
+    });
+    return applyTokenSolution(result);
+  }
+
+  /**
+   * Solve a Friendly Captcha proof-of-work challenge.
+   *
+   * Two different protocols ship under this name and a sitekey does not tell you
+   * which one a site uses, so say which: pass `version: 'v1'` or `version: 'v2'`,
+   * or pass `moduleScript` with the src of the widget's `type="module"` script
+   * tag and let CapSkip read the version off the build the site actually loads.
+   * With neither, v1 is assumed. Solving the wrong version returns a well-formed
+   * token the target site rejects, with nothing to indicate the version was the
+   * problem.
+   *
+   * Pass `api_server: 'eu'` for a sitekey on the EU data-residency tenant; both
+   * tenants mint a token for the same sitekey, so the wrong one is only caught
+   * by the site's own verification.
+   *
+   * The result carries the token as both `code` and `token`. It goes into
+   * `frc-captcha-solution` on v1 and `frc-captcha-response` on v2 -- the field
+   * names differ, which is what catches an integration moved from one to the
+   * other. A v2 token is roughly six kilobytes, so size whatever carries it
+   * accordingly.
+   */
+  async friendlyCaptcha(sitekey, url, options = {}) {
+    const given = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    }
+
+    // Proof-of-work, but not the millisecond kind ALTCHA does: the service sets
+    // the difficulty per request and raises it for addresses it has seen a lot
+    // of, and v2 always solves in a browser. Both make solve time variable
+    // enough to want the longer timeout.
+    const result = await this.solve({
+      timeout: this.recaptchaTimeout,
+      sitekey,
+      url,
+      ...given,
+      method: 'friendly_captcha',
+      poll_json: 1,
+    });
+    return applyTokenSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -318,6 +641,18 @@ class CapSkip {
     if (method === 'geetest') {
       return prepareSubmitParams(params, 'geetest');
     }
+    if (method === 'altcha') {
+      return prepareSubmitParams(params, 'altcha');
+    }
+    if (method === 'capy') {
+      return prepareSubmitParams(params, 'capy');
+    }
+    if (method === 'captchafox') {
+      return prepareSubmitParams(params, 'captchafox');
+    }
+    if (method === 'friendly_captcha') {
+      return prepareSubmitParams(params, 'friendly_captcha');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -330,4 +665,7 @@ module.exports = {
   parseSubmitResponse,
   applyPollResult,
   applyGeetestSolution,
+  applyAltchaSolution,
+  applyCapySolution,
+  applyTokenSolution,
 };

package/types/index.d.ts

@@ -1,6 +1,6 @@
 // Type definitions for the CapSkip Node.js SDK.
 
-/** Proxy passed to reCAPTCHA / Turnstile / GeeTest solves. */
+/** Proxy passed to any solve except image captcha. */
 export interface Proxy {
   /** Proxy type: `HTTP`, `HTTPS`, `SOCKS5`, or `SOCKS5H`. */
   type: string;
@@ -18,7 +18,11 @@ export interface CapSkipOptions {
   port?: number;
   /** Seconds to poll an image captcha before timing out. Default `120`. */
   defaultTimeout?: number;
-  /** Seconds to poll reCAPTCHA / Turnstile / GeeTest before timing out. Default `300`. */
+  /**
+   * Seconds to poll reCAPTCHA / Turnstile / GeeTest / CaptchaFox / Friendly
+   * Captcha before timing out. Default `300`. ALTCHA and Capy use
+   * `defaultTimeout` instead — neither is a browser solve.
+   */
   recaptchaTimeout?: number;
   /** Max seconds between polls; starts at `0.25` and backs off to this. Default `5`. */
   pollingInterval?: number;
@@ -31,10 +35,16 @@ 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.
+   * `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.
+   */
+  code: string | Record<string, unknown>;
+  /**
+   * Turnstile and CaptchaFox — the User-Agent to use when submitting the token.
+   * For CaptchaFox this is the browser's own, not one you sent, and it is absent
+   * when the solve captured none rather than guessed.
    */
-  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;
@@ -42,6 +52,27 @@ export interface SolveResult {
   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;
+  /** Capy only — the value for the target form's `capy_captchakey` field. */
+  captchakey?: string;
+  /** Capy only — the value for the target form's `capy_challengekey` field. */
+  challengekey?: string;
+  /**
+   * Capy only — the value for the target form's `capy_answer` field. The drag
+   * path the widget would have recorded; submit it verbatim.
+   */
+  answer?: string;
+  /**
+   * Capy only — empty for a puzzle solve. Present for shape compatibility with
+   * 2Captcha's documented response; it carries nothing.
+   */
+  respKey?: string;
 }
 
 /** Extra options for {@link CapSkip.normal}. */
@@ -111,6 +142,103 @@ export interface GeetestOptions {
   [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;
+}
+
+/** Extra options for {@link CapSkip.capy}. */
+export interface CapyOptions {
+  /** Root of the Capy API the key lives behind (alias for `api_server`). */
+  apiServer?: string;
+  /** Root of the Capy API the key lives behind. Default `https://jp.api.capy.me`. */
+  api_server?: string;
+  /**
+   * The challenge family. Only `"puzzle"` (the default) is solved — `"avatar"`
+   * is refused before the request is made.
+   */
+  version?: string;
+  /** User-Agent to send with the puzzle request (alias for `useragent`). */
+  userAgent?: string;
+  /** User-Agent to send with the puzzle request. */
+  useragent?: string;
+  /** `1` to request the raw JSON response from CapSkip. */
+  json?: number;
+  /** Proxy — used for the puzzle-image fetch, the only request a Capy solve makes. */
+  proxy?: Proxy | string;
+  /** Proxy type when `proxy` is a bare string. */
+  proxytype?: string;
+  [key: string]: unknown;
+}
+
+/** Extra options for {@link CapSkip.captchafox}. */
+export interface CaptchaFoxOptions {
+  /** Widget entry point (alias for `api_server`). */
+  apiServer?: string;
+  /**
+   * Widget entry point. Default `https://cdn.captchafox.com/`. The MAM package
+   * path returns a `MAM_` prefixed token instead.
+   */
+  api_server?: string;
+  /** Accepted for compatibility and not applied (alias for `useragent`). */
+  userAgent?: string;
+  /** Accepted for compatibility and not applied — CapSkip uses its own browser. */
+  useragent?: 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.friendlyCaptcha}. */
+export interface FriendlyCaptchaOptions {
+  /** Protocol version: `"v1"` (default) or `"v2"`; a bare `1` or `2` works too. */
+  version?: string | number;
+  /** `src` of the widget script tag carrying `type="module"` (alias). */
+  moduleScript?: string;
+  /** `src` of the widget script tag carrying `type="module"`. */
+  module_script?: string;
+  /** `src` of the widget script tag carrying `nomodule` (alias). */
+  nomoduleScript?: string;
+  /** `src` of the widget script tag carrying `nomodule`. */
+  nomodule_script?: string;
+  /** Data residency tenant (alias for `api_server`). */
+  apiServer?: string;
+  /** Data residency tenant: `"global"` (default), `"eu"`, or a full URL. */
+  api_server?: string;
+  /** User-Agent to send with the request (alias for `useragent`). */
+  userAgent?: string;
+  /** User-Agent to send with the request. */
+  useragent?: 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;
+}
+
 /** Options for the {@link CapSkip.solve} manual workflow. */
 export interface SolveOptions {
   /** Poll timeout in seconds (falls back to the configured default). */
@@ -150,6 +278,48 @@ export class CapSkip {
     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>;
+  /**
+   * Solve a Capy Puzzle captcha.
+   *
+   * `sitekey` is the site's public Capy key, conventionally prefixed `PUZZLE_`,
+   * and is sent as the `captchakey` the API documents. The result is not a
+   * token: it carries `captchakey`, `challengekey` and `answer`, all three of
+   * which go into the target form.
+   */
+  capy(sitekey: string, url: string, options?: CapyOptions): Promise<SolveResult>;
+  /**
+   * Solve a CaptchaFox challenge.
+   *
+   * `url` has to be the page the widget actually runs on — CaptchaFox checks it
+   * against the domains the key is registered for. The result carries `token`
+   * for the form's `cf-captcha-response` field.
+   */
+  captchafox(
+    sitekey: string,
+    url: string,
+    options?: CaptchaFoxOptions,
+  ): Promise<SolveResult>;
+  /**
+   * Solve a Friendly Captcha proof-of-work challenge.
+   *
+   * Two different protocols ship under this name and a sitekey does not say
+   * which, so pass `version`, or pass `moduleScript` and let CapSkip read it off
+   * the build the site loads. The token goes into `frc-captcha-solution` on v1
+   * or `frc-captcha-response` on v2.
+   */
+  friendlyCaptcha(
+    sitekey: string,
+    url: string,
+    options?: FriendlyCaptchaOptions,
+  ): 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. */