So lösen Sie hCaptcha Enterprise in Node.js (capskip-SDK)

Um hCaptcha Enterprise in Node.js zu lösen, holen Sie sich von der Website einen neuen rqdata-Wert und übergeben ihn der Methode hcaptcha() des Pakets capskip als Option data, zusammen mit dem sitekey und der Seiten-URL. Die Methode sendet die Aufgabe an CapSkip, fragt ab, bis der Token bereit ist, und gibt ihn zurück. Senden Sie den Token dann mit dem User-Agent aus dem Ergebnis an das Formular. Laut CapSkip-Dokumentation stellt die Website jeden rqdata-Wert für eine Challenge aus, und er läuft schnell ab, daher braucht jede Aufgabe und jede Wiederholung einen frischen. Der folgende Code spricht mit dem CapSkip-hCaptcha-Löser auf Ihrem eigenen Windows-PC, ohne Gebühr pro Lösung.

Was Sie brauchen

• CapSkip in Version 4.0.0 oder höher, installiert auf Ihrem Windows-Rechner. Diese Version brachte das Lösen von hCaptcha, Enterprise eingeschlossen, im hier genutzten Format in.php und im JSON-Format createTask.
• Node.js 18 oder neuer und das Paket capskip in Version 1.6.0 oder höher, der ersten mit einer Methode hcaptcha. Das Paket deklariert Node.js 18 als Untergrenze und hat keine eigenen Abhängigkeiten, und der Formular-POST nutzt das eingebaute fetch. Ich habe den Code nur mit 20.11.1, 24.22.0 und 25.2.1 ausgeführt.
• Eine Website, die Ihnen gehört oder die Sie automatisieren dürfen und die ein hCaptcha-Widget zeigt, und der sitekey dieses Widgets.
• Ein Weg vom Skript zu CapSkip. Der Local-Modus hält CapSkip auf 127.0.0.1, erreichbar von diesem einen Gerät. Der Server-Modus lässt es zusätzlich auf Ihrer Netzwerkadresse oder öffentlichen IP lauschen, sodass auch ein Skript auf einem Windows-VPS, einem anderen PC oder einer gehosteten Plattform es nutzen kann, und er verlangt, dass CapSkip als Administrator läuft. Den Modus wählen Sie in den Verbindungseinstellungen.

Stand der Dinge: Ich habe den Code mit capskip 1.6.0 gegen zwei eigene Mock-Server ausgeführt, einen als Ersatz für CapSkip und einen für eine Enterprise-Website, die jeden rqdata-Wert nur einmal annimmt. Diese Regeln stammen von mir und sind aus der CapSkip-Dokumentation und dem Paketquelltext übernommen. Keine der öffentlichen hCaptcha-Dokumentationsseiten, die ich gelesen habe, beschreibt rqdata, daher stammt jede Tatsache zu rqdata hier aus der CapSkip-Dokumentation. Es fand keine echte Lösung statt, daher kann ich nicht sagen, wie lange eine dauert oder wie sich eine echte Enterprise-Website verhält.

Schritt 1: Den sitekey, das Invisible-Flag und rqdata finden

Führen Sie in einem leeren Ordner npm install capskip aus. Kopieren Sie dann die Blöcke der Schritte 1 bis 4 in der gezeigten Reihenfolge in eine Datei namens hcaptcha-demo.js in diesem Ordner. Bis Schritt 4 läuft nichts, es sei denn, Sie fügen am Ende von Schritt 2 die Testzeile hinzu. Die Option recaptchaTimeout ist das Abfragelimit des SDK für hCaptcha in Sekunden. Der Standardwert ist 300, und die kürzeren 120 habe ich selbst gewählt.

// npm install capskip
const { CapSkip, ApiException } = require("capskip");

const CAPSKIP = { host: "127.0.0.1", port: 8080 }; // Local mode; Server mode: your server
const SITE = "https://www.example.com"; // a site you may automate
const PAGE_URL = `${SITE}/login`; // the page the hCaptcha widget is on
// The SDK's default key. Use your own if API Key Validation is on in CapSkip.
const API_KEY = "capskip";
const PROXY = null; // for example "203.0.113.10:8080"; null means no proxy

const solver = new CapSkip({
  ...CAPSKIP,
  apiKey: API_KEY,
  recaptchaTimeout: 120, // poll limit in seconds for hCaptcha; the default is 300
});

Der sitekey sitzt meist am Widget-Container als data-sitekey. Baut ein Skript das Widget, suchen Sie nach der Option sitekey von hcaptcha.render() oder nach dem Parameter sitekey= in der Adresse des hCaptcha-iframe. Der Leitfaden zum unsichtbaren hCaptcha-Widget kennzeichnet ein unsichtbares Widget mit data-size auf invisible, und laut CapSkip-Dokumentation senden Sie für ein solches Widget invisible=1.

Der rqdata-Wert ist der ungewöhnliche. Laut CapSkip-Dokumentation übergeben manche Enterprise-Websites vor dem Start einen rqdata-Wert über hcaptcha.setData() an das Widget, und wenn die Seite das tut, senden Sie den Wert als data. Tut sie es nicht, senden Sie kein Feld data. Woher der Wert kommt, entscheidet die Website. Er kann im HTML der Seite stehen oder von einer Anfrage zurückkommen, die die Seite macht, durchsuchen Sie daher die Skripte der Seite nach dem Aufruf, der ihn setzt, und verfolgen Sie die Zeichenfolge. Ich habe das an keiner echten Enterprise-Website ausprobiert, und die Funktion unten nutzt den Weg, den mein Mock bereitstellt.

// Ask the site for a new challenge. The route and the field names are the
// site's choice; these are the ones in my test mock, so adapt them.
// If the sitekey is fixed in the page, return it as a constant here.
// If the site puts the values in the page HTML, fetch PAGE_URL and
// extract them here instead.
async function getChallenge() {
  const resp = await fetch(`${SITE}/api/challenge`);
  if (!resp.ok) throw new Error(`challenge failed: HTTP ${resp.status}`);
  const { sitekey, rqdata, invisible } = await resp.json();
  return { sitekey, rqdata, invisible: Boolean(invisible) };
}

Schritt 2: Die Aufgabe senden und den Token abholen

Ein Aufruf sendet die Aufgabe und fragt das Ergebnis ab. Die Methode hcaptcha() nimmt den sitekey, die Seiten-URL und ein Options-Objekt: data ist der rqdata-Wert, invisible ist true für ein unsichtbares Widget, und proxy ist der Proxy für die Lösung. Das SDK sendet sie als Formularfelder mit method=hcaptcha an /in.php und sendet invisible als 1. Es sendet keine Option userAgent: Laut Dokumentation nutzt CapSkip diese Option nur, wenn sie zu dem Browser passt, mit dem es löst, und das Ergebnis trägt den User-Agent, mit dem der Token ausgestellt wurde.

async function solve({ sitekey, rqdata, invisible }) {
  const options = {};
  // The Enterprise rqdata, fresh for this task. Skip it if the site has none.
  if (rqdata) options.data = rqdata;
  if (invisible) options.invisible = true; // data-size is invisible
  if (PROXY) options.proxy = PROXY;
  // Submits the task, polls until the token is ready, and returns the result.
  return solver.hcaptcha(sitekey, PAGE_URL, options);
}

Das SDK fragt /res.php für Sie ab. Die erste Abfrage geht sofort hinaus, und die Wartezeiten danach beginnen bei einer Viertelsekunde, verdoppeln sich jedes Mal und wachsen nicht über 5 Sekunden hinaus. Ein leerer Body gilt als noch nicht bereit: Laut Dokumentation bedeutet er, dass das Ergebnis schon gelesen wurde oder die ID nicht existiert, und der SDK-Quelltext ergänzt, dass CapSkip gleich nach dem Senden einen schickt. Wenn das Limit verstrichen ist, wirft der Aufruf eine TimeoutException.

Ein Ergebnis wird einmal geliefert, und das SDK behält alles davon für Sie. Die Felder code und token enthalten denselben String. Der respKey ist der zweite Wert, den hCaptcha dem Widget mit dem Token übergibt. Laut Dokumentation lesen die meisten Websites ihn nie, und das SDK setzt ihn auf einen leeren String, wenn CapSkip keinen sendet. Lesen Sie userAgent für den User-Agent, mit dem der Token ausgestellt wurde.

Um die Schritte 1 und 2 für sich auszuprobieren, fügen Sie getChallenge().then(solve).then(console.log) als letzte Zeile hinzu und führen node hcaptcha-demo.js aus. Sie sollten ein Objekt mit captchaId, code, userAgent, respKey und token sehen. Löschen Sie diese Zeile wieder, bevor Sie den nächsten Block hinzufügen.

Schritt 3: Den Token an das Formular übergeben

Ein Browser-Widget füllt von selbst zwei versteckte Textarea-Felder, h-captcha-response und eine Spiegelung namens g-recaptcha-response. Ein Skript hat kein Widget und sendet sie daher als Formularfelder. Laut CapSkip-Dokumentation heißt das: immer h-captcha-response, g-recaptcha-response, wenn das Formular auch dieses Feld hat, und der User-Agent aus der Antwort. Das Formular unten ist ein Platzhalter, weil Ihre Website eigene Felder und einen eigenen Weg hat.

Tokens sind nur einmal verwendbar, und laut CapSkip-Dokumentation laufen sie etwa zwei Minuten nach der Ausstellung ab. Die eigene Dokumentation von hCaptcha nennt 120 Sekunden als Standard für den Fehler expired-input-response. Lösen Sie also nicht im Voraus und halten Sie keinen Vorrat an Tokens. Lösen Sie, dann senden Sie, bei jedem Absenden eines Formulars.

async function postForm(solved) {
  const form = new URLSearchParams({
    username: "demo", // the form's own fields
    "h-captcha-response": solved.token,
    // delete the next line if the form has no g-recaptcha-response field
    "g-recaptcha-response": solved.token,
  });
  // Send the User-Agent the reply names, not Node's default one.
  return fetch(PAGE_URL, {
    method: "POST",
    headers: { "User-Agent": solved.userAgent },
    body: form,
  });
}

Schritt 4: Das vollständige Beispiel mit einem frischen rqdata-Wert pro Versuch

Der letzte Block verdrahtet alles zu einer Wiederholungsschleife. Hängen Sie ihn an hcaptcha-demo.js an und starten Sie ihn mit node hcaptcha-demo.js. Jeder Versuch ruft zuerst getChallenge auf, daher trägt jede Aufgabe einen rqdata-Wert, der vor wenigen Augenblicken ausgestellt wurde. Die Schleife wiederholt nur ERROR_CAPTCHA_UNSOLVABLE, den Code für eine Aufgabe, die nicht gelöst werden konnte. Die CapSkip-Dokumentation nennt zwei Fehler, die sich bei einem erneuten Senden wiederholen würden: ERROR_RECAPTCHA_INVALID_SITEKEY bei einer Abfrage, was bedeutet, dass hCaptcha den sitekey für diese Seite abgelehnt hat, und ERROR_PROXY_CONNECT_REFUSED. Die Schleife wirft diese und jeden anderen Fehler unverändert erneut.

Die Schleife läuft auch erneut, wenn die Website außerhalb von 200 bis 299 antwortet, weil ein abgelehnter Token einen veralteten rqdata-Wert bedeuten kann. Eine 403 kann andere Ursachen haben, etwa ein falsches Passwort in einem Anmeldeformular, daher enden die Versuche bei drei.

// ERROR_CAPTCHA_UNSOLVABLE is the one failure where a new task can help.
async function login() {
  for (let attempt = 1; attempt <= 3; attempt += 1) {
    const challenge = await getChallenge(); // a new rqdata for every attempt
    try {
      const solved = await solve(challenge);
      const resp = await postForm(solved);
      if (resp.ok) return resp;
      console.log(`attempt ${attempt}: the site answered HTTP ${resp.status}`);
    } catch (err) {
      // The message is the text of the app's reply: a bare code or small JSON.
      const unsolvable = err instanceof ApiException
        && err.message.includes("ERROR_CAPTCHA_UNSOLVABLE");
      if (!unsolvable) throw err;
      console.log(`attempt ${attempt}: ERROR_CAPTCHA_UNSOLVABLE`);
    }
  }
  throw new Error("hCaptcha not passed in 3 attempts");
}

login()
  .then(async (resp) => console.log(resp.status, await resp.text()))
  .catch((err) => {
    console.error(`${err.name}: ${err.message}`);
    if (err.cause) console.error(err.cause.code); // for example ECONNREFUSED
    process.exitCode = 1;
  });

Das SDK bringt drei eigene Fehler mit. Eine ValidationException bedeutet, dass es den Aufruf ablehnte, bevor es etwas sendete: ein leerer sitekey, eine Seiten-URL, die kein absolutes http oder https ist, ein ungültiger invisible-Wert oder eine Option, die die hCaptcha-API von CapSkip nicht annimmt, etwa domain von 2Captcha. Eine NetworkException beim Senden bedeutet, dass an der Adresse von CapSkip nichts antwortete, und eine TimeoutException bedeutet, dass das Abfragelimit verstrichen ist. Eine neue Aufgabe ändert an keinem davon etwas, daher wirft die Schleife sie erneut. Die Meldung der ApiException enthält die Antwort der App als Text, daher gleicht die Schleife sie mit includes() ab.

So verhielt sich das Skript gegen die Mocks, mit capskip 1.6.0 unter Node.js 24.22.0. Node.js 20.11.1 und 25.2.1 beendeten jeden Fall gleich, mit denselben Exit-Codes. Das Testgerüst änderte nur die Adressen und, in den Timeout-Zeilen, das Abfragelimit.

Häufige Fehler

Proxys und Server-Modus

CapSkip erzwingt für hCaptcha keinen Proxy. Laut Dokumentation reicht eine Adresse zum Testen und für gelegentliche Lösungen, aber hCaptcha bewertet das Netzwerk, aus dem ein Token kommt, ebenso wie den Browser, und ein stetiger Strom von Lösungen von einer IP ist genau das, was seine Ratenbegrenzungen erkennen sollen. Richten Sie bei größeren Mengen in der App unter Settings, Captcha types, hCaptcha, Configure Proxies einen Proxy-Pool ein. Damit eine Lösung aus einem bestimmten Netzwerk kommt, senden Sie mit der Aufgabe einen Proxy, was die Einstellung PROXY tut. Ein mit einer Aufgabe gesendeter Proxy hat immer Vorrang vor der Liste. CapSkip akzeptiert den Proxy als IP:PORT, LOGIN:PASSWORD@IP:PORT oder IP:PORT:LOGIN:PASSWORD. Ein Proxy-String allein geht mit proxytype HTTP hinaus. Für SOCKS5 übergeben Sie proxy als Objekt mit einem type, der HTTP, HTTPS, SOCKS5 oder SOCKS5H annimmt, und einer uri. Gegen den Mock kam das bei in.php als proxytype SOCKS5 an. Eine echte SOCKS5-Lösung habe ich nicht getestet.

Die Einstellung verlegt nur die Lösung. Für eine strenge Website sagt die Dokumentation außerdem, dass das Formular von derselben Adresse gesendet werden soll, aber das in Node.js eingebaute fetch hat keine Proxy-Option pro Anfrage, daher geht der Formular-POST hier von dem PC aus, auf dem das Skript läuft. Den Formular-POST über einen Proxy habe ich nicht getestet.

Der Server-Modus ändert nur, wo der Löser sitzt. Richten Sie die Einstellung CAPSKIP auf den Server aus, und der Rest des Skripts bleibt, wie er ist. Der Server-Modus verlangt, dass CapSkip als Administrator läuft, und eine statische öffentliche IP gibt den stabilsten Fernzugriff. Der Löser ist weiterhin Ihre eigene Hardware, ohne Gebühr pro Lösung. CapSkip nimmt dann Verbindungen von jeder Adresse an, fügen Sie daher eine Blockierregel der Windows Firewall für die Adressen hinzu, die es nicht erreichen sollen, schalten Sie API Key Validation in CapSkip ein und tragen Sie API_KEY ein. Die Lösung läuft nun auf dem Windows-VPS, daher sieht hCaptcha das Netzwerk dieses Rechners oder den Proxy, den Sie übergeben.

FAQ

Was die Website Ihnen auch entgegenstellt: hCaptcha Enterprise in Node.js zu lösen bleibt eine einzige Schleife, mit einem frischen rqdata-Wert, einer neuen Aufgabe und einem sofort gesendeten Token. Wenn Sie sie über einen Captcha-Löser auf Ihrem eigenen Rechner ausführen, fällt bei einer Wiederholung keine Gebühr pro Lösung an. Weitere Node.js-Werkzeuge finden Sie auf der Node.js-Captcha-Solver-Seite, und jeder Parameter steht im hCaptcha-Abschnitt der API-Dokumentation.