capskip 1.2.0 → 1.4.0

package/src/solver.js

@@ -217,6 +217,90 @@ function applyAltchaSolution(result) {
   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'];
+
+/**
+ * Copy `fields` out of an answer that is an object rather than a token.
+ *
+ * `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 expandObjectAnswer(result, fields) {
+  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 fields) {
+    if (Object.prototype.hasOwnProperty.call(payload, field)) {
+      result[field] = payload[field];
+    }
+  }
+
+  return result;
+}
+
+/** Expand the Capy answer into `captchakey` / `challengekey` / `answer`. */
+function applyCapySolution(result) {
+  return expandObjectAnswer(result, CAPY_FIELDS);
+}
+
+// An AWS WAF solution is two values that only work as a pair: the voucher AWS
+// issued for the answered puzzle, and the token it was issued for. The site's
+// own /voucher endpoint trades them for the aws-waf-token cookie.
+const AMAZON_WAF_FIELDS = ['captcha_voucher', 'existing_token'];
+
+/** Expand the AWS WAF answer into `captcha_voucher` / `existing_token`. */
+function applyAmazonWafSolution(result) {
+  return expandObjectAnswer(result, AMAZON_WAF_FIELDS);
+}
+
+/**
+ * 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) {
@@ -240,7 +324,10 @@ function parseSubmitResponse(response) {
   throw new ApiException(`cannot recognize response ${response}`);
 }
 
-/** Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile, GeeTest v3, ALTCHA). */
+/**
+ * Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile,
+ * GeeTest v3, ALTCHA, Capy Puzzle, CaptchaFox, Friendly Captcha, AWS WAF).
+ */
 class CapSkip {
   constructor({
     apiKey = 'capskip',
@@ -359,6 +446,180 @@ class CapSkip {
     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);
+  }
+
+  /**
+   * Solve an AWS WAF (Amazon WAF) CAPTCHA.
+   *
+   * Only `sitekey` and `url` are required:
+   *
+   * - On a challenge page (the HTTP 405 page with `window.gokuProps`), `sitekey`
+   *   is `gokuProps.key`, and `iv` and `context` are `gokuProps.iv` and
+   *   `gokuProps.context`. Send both or neither -- left out, CapSkip reads them
+   *   from `url` at solve time, which is the safer choice when your copy of the
+   *   page is more than a few minutes old. `challenge_script` and
+   *   `captcha_script` are the full URLs of the page's challenge.js and
+   *   captcha.js.
+   * - On a widget page (`AwsWafCaptcha.renderCaptcha`), `sitekey` is the
+   *   widget's `apiKey`; pass `jsapiScript` with the full URL of jsapi.js and no
+   *   `iv` / `context`.
+   *
+   * Every script URL must be an https URL on an awswaf.com host; anything else
+   * is refused before the request is sent.
+   *
+   * The result carries `captcha_voucher` and `existing_token`, plus the raw
+   * answer as `code`. The two only work as a pair: POST them as JSON to the
+   * `voucher` endpoint next to the page's challenge.js and the response's
+   * `token` is the aws-waf-token cookie. Exchange them as soon as they arrive
+   * rather than storing them for later.
+   */
+  async amazonWaf(sitekey, url, options = {}) {
+    // An unset optional is dropped rather than sent as undefined; an empty one
+    // is dropped during validation, since the server reads '' as "not sent".
+    const given = {};
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    }
+
+    // A real browser mints the token the voucher is issued for, and the puzzle
+    // rounds go through AWS on top of that, 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: 'amazon_waf',
+      poll_json: 1,
+    });
+    return applyAmazonWafSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -450,6 +711,18 @@ class CapSkip {
     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');
+    }
+    if (method === 'amazon_waf') {
+      return prepareSubmitParams(params, 'amazon_waf');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -463,4 +736,8 @@ module.exports = {
   applyPollResult,
   applyGeetestSolution,
   applyAltchaSolution,
+  applyCapySolution,
+  applyAmazonWafSolution,
+  expandObjectAnswer,
+  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 / AWS WAF 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;
@@ -32,10 +36,15 @@ 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. For ALTCHA it is the
-   * base64 token, also exposed as `token`.
+   * base64 token, also exposed as `token`. For Capy and AWS WAF it is the raw
+   * answer object, expanded into the 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;
@@ -50,6 +59,29 @@ export interface SolveResult {
   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;
+  /**
+   * AWS WAF only — the voucher AWS issued for the answered puzzle. Only valid
+   * together with `existing_token`: POST both as JSON to the `voucher` endpoint
+   * beside the page's challenge.js, whose response `token` is the
+   * `aws-waf-token` cookie. Exchange immediately.
+   */
+  captcha_voucher?: string;
+  /** AWS WAF only — the token the voucher was issued for. Pair with `captcha_voucher`. */
+  existing_token?: string;
 }
 
 /** Extra options for {@link CapSkip.normal}. */
@@ -141,6 +173,113 @@ export interface AltchaOptions {
   [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;
+}
+
+/** Extra options for {@link CapSkip.amazonWaf}. */
+export interface AmazonWafOptions {
+  /**
+   * Challenge page: `gokuProps.iv`. Send together with `context`, or leave both
+   * out and CapSkip reads them from the page at solve time.
+   */
+  iv?: string;
+  /** Challenge page: `gokuProps.context`. Send together with `iv`. */
+  context?: string;
+  /** Full https URL of the page's `challenge.js` on an `awswaf.com` host. */
+  challenge_script?: string;
+  /** Full https URL of the page's `challenge.js` (alias for `challenge_script`). */
+  challengeScript?: string;
+  /** Full https URL of the page's `captcha.js` on an `awswaf.com` host. */
+  captcha_script?: string;
+  /** Full https URL of the page's `captcha.js` (alias for `captcha_script`). */
+  captchaScript?: string;
+  /** Widget page: full https URL of `jsapi.js` on an `awswaf.com` host. */
+  jsapiScript?: string;
+  /** Widget page: full https URL of `jsapi.js` (alias for `jsapiScript`). */
+  jsapi_script?: string;
+  /** Poll timeout in seconds. Default: the client's `recaptchaTimeout`. */
+  timeout?: number;
+  /** `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). */
@@ -188,6 +327,55 @@ export class CapSkip {
    * 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>;
+  /**
+   * Solve an AWS WAF CAPTCHA.
+   *
+   * On a challenge page, `sitekey` is `gokuProps.key` and `iv` / `context` are
+   * `gokuProps.iv` / `gokuProps.context` (both or neither). On a widget page,
+   * `sitekey` is the widget's `apiKey`; pass `jsapiScript`. Script URLs must be
+   * https on an `awswaf.com` host. The result carries `captcha_voucher` and
+   * `existing_token`, which the site's `voucher` endpoint trades for the
+   * `aws-waf-token` cookie.
+   */
+  amazonWaf(
+    sitekey: string,
+    url: string,
+    options?: AmazonWafOptions,
+  ): 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. */