capskip 1.3.0 → 1.5.0

package/src/solver.js

@@ -83,6 +83,12 @@ function applyPollResult(result, polled) {
     if (userAgent) {
       result.userAgent = userAgent;
     }
+    // DataDome names the proxy a task was solved through when the task sent
+    // none and CapSkip took one from its own DataDome proxy list. The cookie
+    // only works from that address, so it is reported rather than dropped.
+    if (polled.proxy) {
+      result.proxy = polled.proxy;
+    }
     // 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
@@ -222,7 +228,7 @@ function applyAltchaSolution(result) {
 const CAPY_FIELDS = ['captchakey', 'challengekey', 'answer', 'respKey'];
 
 /**
- * Expand the Capy answer into `captchakey` / `challengekey` / `answer`.
+ * 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
@@ -232,7 +238,7 @@ const CAPY_FIELDS = ['captchakey', 'challengekey', 'answer', 'respKey'];
  * If the answer does not parse, the result is returned untouched rather than
  * masking the server's reply.
  */
-function applyCapySolution(result) {
+function expandObjectAnswer(result, fields) {
   let payload = result.solution;
   delete result.solution;
 
@@ -253,7 +259,7 @@ function applyCapySolution(result) {
     return result;
   }
 
-  for (const field of CAPY_FIELDS) {
+  for (const field of fields) {
     if (Object.prototype.hasOwnProperty.call(payload, field)) {
       result[field] = payload[field];
     }
@@ -262,6 +268,39 @@ function applyCapySolution(result) {
   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 the DataDome cookie as `cookie`, ready for a Cookie header.
+ *
+ * `code` keeps the cookie exactly as DataDome set it, attributes included
+ * (`datadome=...; Max-Age=...; Domain=...; Path=/; Secure; SameSite=Lax`),
+ * for a cookie jar. `cookie` is the part before the first semicolon, the
+ * `datadome=...` pair a request sends back. `userAgent` and, when CapSkip
+ * picked the proxy, `proxy` are carried through from the poll as they are.
+ * An answer that is not a string is left untouched.
+ */
+function applyDataDomeSolution(result) {
+  const { code } = result;
+  if (typeof code === 'string' && code) {
+    result.cookie = code.split(';', 1)[0].trim();
+  }
+  return result;
+}
+
 /**
  * Expose a single-token answer as `token`, named for the form field it fills.
  *
@@ -309,7 +348,11 @@ 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,
+ * DataDome).
+ */
 class CapSkip {
   constructor({
     apiKey = 'capskip',
@@ -553,6 +596,110 @@ class CapSkip {
     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);
+  }
+
+  /**
+   * Solve a DataDome challenge and return the `datadome` cookie.
+   *
+   * `captchaUrl` and `url` are required; everything else goes in `options`:
+   *
+   * - `captchaUrl` is the address of the challenge iframe on
+   *   geo.captcha-delivery.com, under /captcha/ (slider) or /interstitial/
+   *   (device check). Take the iframe's src from the block page, or build it
+   *   from the page's `var dd` object as the API docs show.
+   * - `url` is the page that returned the block page.
+   * - `options.userAgent` is the one you will send with the cookie. It must be
+   *   Chrome for Windows with the same major version as the browser CapSkip
+   *   solves with; leave it out and CapSkip uses that browser's own.
+   * - `options.proxy` is the proxy your later requests go through, as a URI
+   *   string or `{ type: 'HTTP', uri: 'login:password@IP:PORT' }`.
+   *
+   * DataDome ties the cookie to the IP address and User-Agent that earned it.
+   * The result carries:
+   *
+   * - `code` -- the cookie exactly as DataDome set it, attributes included;
+   * - `cookie` -- just the `datadome=...` pair, for a Cookie header;
+   * - `userAgent` -- the User-Agent the cookie was earned with. Send it with
+   *   every request that carries the cookie;
+   * - `proxy` -- present only when you sent no proxy and CapSkip solved
+   *   through its own DataDome proxy list: that proxy as `host:port`. The
+   *   cookie works only through it.
+   */
+  async dataDome(captchaUrl, url, options = {}) {
+    // An unset value is dropped rather than sent as undefined, so
+    // `dataDome(undefined, url, { captchaUrl })` reaches the alias without
+    // tripping the conflict check; an empty one is dropped during validation,
+    // since the server reads '' as "not sent".
+    const given = {};
+    const add = (key, value) => {
+      if (value !== undefined && value !== null) {
+        given[key] = value;
+      }
+    };
+    add('captcha_url', captchaUrl);
+    add('url', url);
+    for (const [key, value] of Object.entries(options)) {
+      add(key, value);
+    }
+
+    // A real browser session, slider or device check, 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,
+      ...given,
+      method: 'datadome',
+      poll_json: 1,
+    });
+    return applyDataDomeSolution(result);
+  }
+
   async solve(options = {}) {
     const {
       timeout = 0,
@@ -653,6 +800,12 @@ class CapSkip {
     if (method === 'friendly_captcha') {
       return prepareSubmitParams(params, 'friendly_captcha');
     }
+    if (method === 'amazon_waf') {
+      return prepareSubmitParams(params, 'amazon_waf');
+    }
+    if (method === 'datadome') {
+      return prepareSubmitParams(params, 'datadome');
+    }
     return applyProxy(applyParamAliases(params));
   }
 }
@@ -667,5 +820,8 @@ module.exports = {
   applyGeetestSolution,
   applyAltchaSolution,
   applyCapySolution,
+  applyAmazonWafSolution,
+  applyDataDomeSolution,
+  expandObjectAnswer,
   applyTokenSolution,
 };

package/types/index.d.ts

@@ -20,7 +20,7 @@ export interface CapSkipOptions {
   defaultTimeout?: number;
   /**
    * Seconds to poll reCAPTCHA / Turnstile / GeeTest / CaptchaFox / Friendly
-   * Captcha before timing out. Default `300`. ALTCHA and Capy use
+   * Captcha / AWS WAF / DataDome before timing out. Default `300`. ALTCHA and Capy use
    * `defaultTimeout` instead — neither is a browser solve.
    */
   recaptchaTimeout?: number;
@@ -36,14 +36,17 @@ 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`. For Capy it is the raw answer
-   * object, expanded into the three fields below.
+   * base64 token, also exposed as `token`. For Capy and AWS WAF it is the raw
+   * answer object, expanded into the fields below. For DataDome it is the
+   * `datadome` cookie exactly as DataDome set it, attributes included.
    */
   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.
+   * Turnstile, CaptchaFox and DataDome — 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. For DataDome
+   * it is the User-Agent the cookie was earned with — the one you sent, or
+   * CapSkip's own browser's — and every request carrying the cookie must send it.
    */
   userAgent?: string;
   /** GeeTest only — the `geetest_challenge` value to post back. */
@@ -73,6 +76,26 @@ export interface SolveResult {
    * 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;
+  /**
+   * DataDome only — the `datadome=...` pair alone (`code` up to its first
+   * `;`), ready for a `Cookie` header.
+   */
+  cookie?: string;
+  /**
+   * DataDome only — present only when the task sent no proxy and CapSkip solved
+   * through its own DataDome proxy list: that proxy as `host:port`. The cookie
+   * works only through it.
+   */
+  proxy?: string;
 }
 
 /** Extra options for {@link CapSkip.normal}. */
@@ -239,6 +262,68 @@ export interface FriendlyCaptchaOptions {
   [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;
+}
+
+/** Extra options for {@link CapSkip.dataDome}. */
+export interface DataDomeOptions {
+  /**
+   * The User-Agent you will send with the cookie. Must be stock Chrome for
+   * Windows with the same major version as the browser CapSkip solves with.
+   * Leave it out and CapSkip uses its own browser's, reported as `userAgent`.
+   */
+  userAgent?: string;
+  /** Alias for `userAgent`. */
+  useragent?: string;
+  /** The challenge iframe URL (alias for the `captchaUrl` argument). */
+  captcha_url?: string;
+  /** The challenge iframe URL (alias for the `captchaUrl` argument). */
+  captchaUrl?: string;
+  /**
+   * The proxy your later requests go through. Left out, CapSkip solves through
+   * its own DataDome proxy list and the result names that proxy as `proxy`.
+   */
+  proxy?: Proxy | string;
+  /** Proxy type when `proxy` is a bare string. Default `HTTP`. */
+  proxytype?: string;
+  /** Poll timeout in seconds. Default: the client's `recaptchaTimeout`. */
+  timeout?: number;
+  /** Max seconds between polls for this solve. */
+  polling_interval?: number;
+  /** `1` to request the raw JSON response from CapSkip. */
+  json?: number;
+  [key: string]: unknown;
+}
+
 /** Options for the {@link CapSkip.solve} manual workflow. */
 export interface SolveOptions {
   /** Poll timeout in seconds (falls back to the configured default). */
@@ -320,6 +405,37 @@ export class CapSkip {
     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>;
+  /**
+   * Solve a DataDome challenge (slider or device check) and return the
+   * `datadome` cookie.
+   *
+   * `captchaUrl` is the challenge iframe's address on captcha-delivery.com
+   * (`/captcha/` or `/interstitial/`), `url` the page that returned the block
+   * page. The result carries `code` (the cookie as set), `cookie` (the
+   * `datadome=...` pair), `userAgent` (send it with the cookie) and, only when
+   * no proxy was passed and CapSkip used its own DataDome proxy list, `proxy`
+   * — the cookie works only through that address.
+   */
+  dataDome(
+    captchaUrl: string | undefined,
+    url: string,
+    options?: DataDomeOptions,
+  ): 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. */