Electron-Captcha: Turnstile im main process lösen

electron captcha - Electron CAPTCHA: Solve Turnstile From the Main Process

Um ein Captcha aus einer Electron-App zu lösen, lassen Sie die Arbeit im main process. Laden Sie die Seite in einem BrowserWindow, lesen Sie den sitekey mit webContents.executeJavaScript aus, fordern Sie mit dem Node SDK capskip einen Token von CapSkip an, stellen Sie das Fenster auf den User-Agent um, den der Solver meldet, schreiben Sie den Token in das versteckte Feld und senden Sie das Formular ab. Dieser Electron-Captcha-Leitfaden richtet sich an Entwickler, die ein Turnstile-Widget innerhalb einer Electron-App bestehen müssen, nicht an alle, die eines in die eigene Website einbauen. Der renderer fordert den Job per IPC an und sieht den API key nie. Jeder Token stammt vom CapSkip Turnstile Solver auf einem Windows-PC, den Sie besitzen.

Was Sie brauchen

  • Ein Windows-PC, auf dem CapSkip wie in der Einrichtungsanleitung beschrieben installiert ist und im Local mode läuft, der auf 127.0.0.1:8080 lauscht.
  • Node.js 22.12 oder neuer für npm, die Untergrenze, die das Paket electron deklariert. Das Paket capskip deklariert Node.js 18, was das Node.js in Electron 45.3.0 erfüllt: Es meldete 24.22.2. Bei meinem Lauf verbrachte der erste Start 21,9 Sekunden mit dem Download des Electron-Programms, das npm install nicht geladen hatte.
  • Eine Seite mit einem Turnstile-Widget, die Sie automatisieren dürfen.
  • Eine Adresse für CapSkip, die dazu passt, wo die App läuft. Local mode bedient nur den eigenen PC, und Server mode lauscht auf Ihrem Netzwerk oder Ihrer öffentlichen IP, was eine ausgelieferte App braucht (siehe den letzten Abschnitt).

Ich habe Turnstile gewählt, weil sein Widget den Token in einem einfachen versteckten Input hält und sein Ergebnis den User-Agent enthält, den der Solver benutzt hat, während eine Electron-Seite mit einem anderen geladen wird. Dieser Konflikt ist der Teil der Aufgabe, der zu Electron gehört.

Alles lief unter Windows 11 mit Electron 45.3.0 (Chrome 156.0.8078.96) und capskip 1.7.0, gegen zwei Mocks, die ich geschrieben habe: Einer spielt CapSkip, einer eine Kontaktseite mit einem Turnstile-förmigen Widget. Der Token-Text und jede Website-Regel stammen von mir, und die echte CapSkip-App bekam keinen Task. Ein Wrapper startete dieselbe main.js, versteckte jedes Fenster beim Öffnen und klickte den Button per Skript; ein Lauf mit sichtbaren Fenstern stimmte überein. Ich habe die App nie paketiert.

Schritt 1: Zwei Fenster, ein preload und die IPC-Brücke

Legen Sie einen leeren Ordner an und führen Sie diese drei Befehle aus. Der letzte lässt npm das Projekt über main.js starten.

# npm install electron capskip
npm init -y
npm install electron capskip
npm pkg set main=main.js

Die App braucht zwei Fenster. Eines zeigt Ihre eigene Oberfläche und bekommt ein preload-Skript. Das andere lädt die Seite mit dem Captcha und bekommt nichts, sodass ein Skript auf dieser Seite keine Brücke zu Ihrem main process hat. Ich habe contextIsolation, nodeIntegration und sandbox ausdrücklich gesetzt, aber ein Fenster ohne webPreferences meldete in Electron 45.3.0 dieselben Werte, und der Electron-Sicherheitsleitfaden datiert diese Standardwerte auf die Versionen 12, 5 und 20.

// main.js
const { app, BrowserWindow, ipcMain } = require("electron");
const { once } = require("node:events");
const path = require("node:path");
const { CapSkip } = require("capskip");

// The page that shows the Turnstile widget.
const SITE_URL = process.env.SITE_URL || "https://example.com/contact";

// The only place that knows the host and the key. Local mode by default.
const solver = new CapSkip({
  host: process.env.CAPSKIP_HOST || "127.0.0.1",
  port: Number(process.env.CAPSKIP_PORT || 8080),
  apiKey: process.env.CAPSKIP_API_KEY || "capskip",
});

let ui;
let site;
let busy = false;

// The page with the CAPTCHA: no preload, so nothing is exposed to it.
function createSite() {
  return new BrowserWindow({
    width: 900,
    height: 700,
    webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
  });
}

app.whenReady().then(() => {
  // Your own interface: the only window that gets the preload script.
  ui = new BrowserWindow({
    width: 480,
    height: 320,
    webPreferences: {
      preload: path.join(__dirname, "preload.js"),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: true,
    },
  });
  ui.loadFile("index.html");
  site = createSite();
});

app.on("window-all-closed", () => app.quit());

CapSkip wird einmal hier aufgebaut, und Host, Port und Schlüssel kommen aus Umgebungsvariablen, die Sie selbst lesen, weil das SDK keine liest. Das preload stellt nur eine einzige Funktion bereit, nie das ganze ipcRenderer, und invoke wird mit dem aufgelöst, was der Handler des main process zurückgibt.

// preload.js
const { contextBridge, ipcRenderer } = require("electron");

// Expose one narrow function, never ipcRenderer itself.
contextBridge.exposeInMainWorld("captcha", {
  send: (email) => ipcRenderer.invoke("captcha:send", email),
});

Das Oberflächenskript liegt in einer eigenen Datei, damit seine eigene Content-Security-Policy Skripte nur von self erlauben kann, wie es der Sicherheitsleitfaden empfiehlt.

<!-- index.html -->
<!doctype html>
<meta charset="utf-8">
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'">
<title>Send with CAPTCHA</title>
<input id="email" value="[email protected]">
<button id="go">Solve and send</button>
<pre id="out"></pre>
<script src="renderer.js"></script>
// renderer.js
const go = document.getElementById("go");
const out = document.getElementById("out");

go.addEventListener("click", async () => {
  go.disabled = true;
  out.textContent = "Solving";
  const reply = await window.captcha.send(document.getElementById("email").value);
  out.textContent = JSON.stringify(reply, null, 2);
  go.disabled = false;
});

In beiden Fenstern waren require und process undefiniert; window.captcha hielt im Oberflächenfenster einen Schlüssel, send, und war im Seitenfenster undefiniert; und der API key tauchte im HTML keiner der beiden Seiten auf. Ein Probe-Fenster mit demselben preload, das aber eine andere Seite zeigte, bekam eine Ablehnung vom Sender-Check des Handlers, den der Electron-Sicherheitsleitfaden verlangt.

Schritt 2: Der Handler, der löst und absendet

Fügen Sie dies unter dem ersten Teil von main.js ein. Es lädt die Seite, liest den sitekey aus dem Attribut data-sitekey des Widgets, ruft solver.turnstile auf, übernimmt den gemeldeten User-Agent, füllt das Formular aus und wartet auf die Seite, die zurückkommt.

// main.js, continued below the first part
// Read the sitekey from the page, solve, set the User-Agent, fill, submit.
async function solveAndSend(email) {
  // The user may have closed the page window since the last job.
  if (!site || site.isDestroyed()) site = createSite();
  await site.loadURL(SITE_URL);
  const web = site.webContents;

  const sitekey = await web.executeJavaScript(
    `document.querySelector("[data-sitekey]")?.dataset.sitekey ?? null`
  );
  if (!sitekey) return { ok: false, error: "no widget on the page" };

  // Turnstile polls on defaultTimeout; this call is capped at 60 seconds.
  const solved = await solver.turnstile(sitekey, web.getURL(), { timeout: 60 });
  if (web.isDestroyed()) return { ok: false, error: "window closed" };

  // Submit with the User-Agent the token was earned with.
  if (solved.userAgent) web.setUserAgent(solved.userAgent);

  // JSON.stringify keeps a quote in a value from breaking out of the string.
  const fill = `(() => {
    const form = document.querySelector("form");
    form.elements["email"].value = ${JSON.stringify(email)};
    let field = form.elements["cf-turnstile-response"];
    if (!field) {
      field = Object.assign(document.createElement("input"), { type: "hidden", name: "cf-turnstile-response" });
      form.appendChild(field);
    }
    field.value = ${JSON.stringify(solved.code)};
    form.requestSubmit();
  })()`;
  const loaded = once(web, "did-finish-load");
  await web.executeJavaScript(fill);
  await loaded;

  const page = await web.executeJavaScript("document.body.innerText");
  return { ok: true, page: page.trim().slice(0, 80) };
}

ipcMain.handle("captcha:send", async (event, email) => {
  if (event.sender !== ui.webContents) return { ok: false, error: "refused" };
  if (typeof email !== "string" || email.length > 200) {
    return { ok: false, error: "bad email" };
  }
  if (busy) return { ok: false, error: "busy" };
  busy = true;
  try {
    return await solveAndSend(email);
  } catch (err) {
    // An Error thrown here reaches the renderer as a message only.
    return { ok: false, error: err.constructor.name, message: err.message };
  } finally {
    busy = false;
  }
});

Vier Details sind wichtig. Erstens enthielt in 1.7.0 eine Turnstile-Antwort captchaId, code und userAgent und kein Feld token, der Token ist also code. Zweitens sagt die Antwort ok, wenn das Formular abgesendet wurde, nicht wenn die Website den Token akzeptiert hat: Mit übersprungenem User-Agent-Schritt antwortete mein Mock der App mit ok, und auf der Seite stand Verification failed, suchen Sie also nach dem Erfolgstext Ihrer eigenen Website. Drittens: Der Rendering-Leitfaden von Cloudflare sagt, dass implizites Rendering ein unsichtbares Input namens cf-turnstile-response hinzufügt und dass Tokens nach 300 Sekunden ablaufen und nur einmal gültig sind. Wenn Ihre Seite einen Callback ausführt, sobald das Widget fertig ist, rät die CapSkip-API-Dokumentation, ihn mit dem Token auszuführen; das habe ich nicht getestet. Ich habe das echte Widget-Skript von Cloudflare einmal in einem versteckten Fenster geladen, mit einem sitekey, den Cloudflare zum Testen veröffentlicht, und das Input erschien etwa 2,5 Sekunden nach dem Laden, deshalb legt der Code das Feld an, wenn es fehlt. Ich habe diesen Token nirgends abgesendet und nicht getestet, ob das Widget einen von Ihnen gesetzten Wert überschreibt. Viertens baut JSON.stringify die Werte in das Skript ein, und eine E-Mail mit Anführungszeichen und einem Backslash erreichte meinen Mock unverändert.

Zeitlimits und ein geschlossenes Fenster

Turnstile pollt mit dem Standard-Timeout des Clients von 120 Sekunden, nicht mit dem längeren von reCAPTCHA: Mit defaultTimeout 5 und recaptchaTimeout 300 endete ein Mock, der nie antwortete, nach 7,8 Sekunden in TimeoutException. Die Option timeout gilt pro Aufruf, in Sekunden, und ich habe 60 gesetzt. Das SDK prüft die Frist nur, wenn die nächste Abfrage fällig ist, deshalb brauchte ein Mock, der nie antwortete, 63,0 Sekunden vom Klick bis zur Antwort. ipcRenderer.invoke hat kein eigenes Timeout: Ein Handler, der nie zurückkehrte, ließ den Aufruf offen, als ich nach 20 Sekunden aufhörte zuzusehen. Das SDK-Timeout ist Ihre einzige Grenze.

Das SDK lässt sich nicht abbrechen. Als ich das Seitenfenster 1,5 Sekunden nach Beginn einer 4 Sekunden langen Mock-Lösung schloss, fragte das SDK weiter ab, und die Antwort kam nach 7,9 Sekunden. Ohne die Prüfung isDestroyed warf setUserAgent TypeError: Object has been destroyed, und ohne createSite scheiterte jeder spätere Klick auf dieselbe Weise; mit beiden öffnete der nächste Klick ein neues Seitenfenster und gelang. Ein zweiter Klick während einer Lösung bekam die Antwort busy, da ein Seitenfenster nicht zwei Jobs bedienen kann.

Ein in einem Handler geworfener Error erreicht den renderer nur als Nachricht: Meine Probe warf MyErr mit einer Eigenschaft code, und der renderer sah einen einfachen Error. Deshalb fängt der Handler alles ab und gibt ein Objekt zurück, das Klassennamen und Nachricht der SDK-Exception behält.

Schritt 3: Was die Content-Security-Policy der Seite blockiert

Die Electron-Dokumentation zu executeJavaScript erwähnt keine Content-Security-Policy, also habe ich es getestet. Ich habe die Mock-Seite ohne Policy und mit einer Policy script-src self geladen und dieselben Proben in der main world ausgeführt.

ProbeKeine PolicyPolicy script-src self
Inline-Skript im eigenen HTML der SeiteLiefBlockiert
Skriptdatei vom eigenen Origin der SeiteLiefLief
executeJavaScript setzt das versteckte InputFunktionierteFunktionierte
eval() oder new Function() im ausgeführten Code aufrufenFunktionierteEvalError
Ein script-Element mit Inline-Text, das der ausgeführte Code hinzufügtLiefBlockiert
eval() in executeJavaScriptInIsolatedWorldFunktionierteFunktionierte

Der Code, den Sie an executeJavaScript übergeben, läuft, aber die Policy gilt weiterhin für alles, was er aus Strings baut. Setzen Sie Eigenschaften und rufen Sie vorhandene Funktionen auf, dann hat die Policy nichts mitzureden. Der vollständige Ablauf aus Schritt 2 lief gegen die Seite mit script-src, und eine Policy default-src none, die auch die eigene Skriptdatei der Seite blockierte, ließ trotzdem zu, dass das versteckte Input gesetzt wurde.

Schritt 4: Der User-Agent, mit dem die Seite lädt

Ein Electron-Fenster identifiziert sich mit einem Electron-Eintrag: Mein Mock sah Chrome/156.0.8078.96 Electron/45.3.0. Die CapSkip-API-Dokumentation sagt, man solle beim Absenden eines Turnstile-Tokens den User-Agent des Solvers senden, und das Node SDK lässt Sie ihn nicht wählen: userAgent und useragent lösten beide ValidationException mit Unsupported parameters for Turnstile aus. Der Handler ruft webContents.setUserAgent auf, nachdem die Seite geladen ist; mein Mock hat für fünf Arten, ihn zu setzen, diese Ergebnisse aufgezeichnet.

Art, ihn zu setzennavigator.userAgentRequest-Header
webContents.setUserAgent nach dem Laden der SeiteSofort geändert, ohne NeuladenDer des Solvers beim nächsten Absenden des Formulars
webContents.setUserAgent vor loadURLDer des SolversDer des Solvers beim Laden der Seite und beim Absenden
session.setUserAgent auf einer eigenen Session oder die Option userAgent von loadURLDer des SolversDer des Solvers bei beiden
Ein webRequest-Hook onBeforeSendHeadersWeiterhin der Electron-StringDer des Solvers bei beiden

Der Hook ist der Ausreißer: Ein Seitenskript, das navigator.userAgent liest, sieht weiterhin Electron, während der Server etwas anderes sieht. Die App erfährt den User-Agent erst, wenn die Seite offen ist, deshalb passt der Aufruf nach dem Laden. Keine meiner Anfragen trug einen Header sec-ch-ua, und nach setUserAgent nannte die Liste navigator.userAgentData.brands weiterhin Chromium 156, die beiden widersprechen sich also. Chromium hat Referer und Origin selbst zur Formularübermittlung hinzugefügt. Die User-Agent-Prüfung ist die Regel meines Mocks: Ich habe keine echte Website getestet, ob eine die beiden vergleicht, ist also ungetestet.

Ausführen, und Server mode für eine ausgelieferte App

Setzen Sie die Seitenadresse und starten Sie dann die App. Die beiden auskommentierten Zeilen sind nur für Server mode; lassen Sie sie in Ruhe, solange CapSkip auf demselben PC läuft.

# Run from the project folder in PowerShell
$env:SITE_URL = "https://example.com/contact"
# Server mode only: another PC runs CapSkip
# $env:CAPSKIP_HOST = "192.168.1.50"
# $env:CAPSKIP_API_KEY = "YOUR_API_KEY"
npx electron .

Eine App, die Sie ausliefern, kann sich nicht darauf verlassen, dass 127.0.0.1 ein CapSkip hält. Entweder betreibt jeder Nutzer CapSkip in Local mode auf seinem eigenen PC, und der Code bleibt, wie er ist, oder Sie betreiben CapSkip auf einem Windows-Rechner, den Sie kontrollieren, in Server mode, wo es auf Ihrem Netzwerk oder einer öffentlichen IP lauscht, und CAPSKIP_HOST benennt diesen Rechner. CAPSKIP_PORT tut dasselbe für einen anderen Port als 8080. Die Verbindungseinstellungen enthalten den Schalter. Die Einrichtungsanleitung sagt, dass Server mode verlangt, dass CapSkip als Administrator läuft, und eine statische Adresse hält die App auf dasselbe Ziel gerichtet.

Drei Warnungen folgen. CapSkip öffnet seinen Port für alle Adressen, wenn Server mode startet. Um ihn auf die erwarteten Rechner zu beschränken, fügen Sie also eine Block-Regel der Windows-Firewall für die übrigen hinzu und schalten Sie API Key Validation ein. Das SDK baut eine http-Adresse ohne TLS-Option, daher läuft der Schlüssel jenseits eines LAN oder VPN im Klartext. Und ein Schlüssel in einer App, die Sie verteilen, kann von jedem gelesen werden, der sie ausführt, behandeln Sie ihn also als öffentlich. Die letzten beiden sind meine Lesart des SDK-Quelltexts, kein Test.

Häufige Fehler

Mit mock markierte Zeilen sind das, was mein Mock durch das echte SDK zurückgab; der Rest folgt der CapSkip-Dokumentation.

Antwort des HandlersUrsacheBeheben
ApiException mit ERROR_KEY_DOES_NOT_EXIST (mock)API Key Validation ist an, und der gesendete Schlüssel ist falsch. Ohne CAPSKIP_API_KEY sendet das SDK capskipCAPSKIP_API_KEY setzen
NetworkException mit connect ECONNREFUSED (mock port)Nichts lauscht auf diesem Host und PortStarten Sie CapSkip oder korrigieren Sie CAPSKIP_HOST und den Port
TimeoutException mit timeout 60 exceeded (mock)Kein Token innerhalb des Aufruf-Timeouts; die Antwort kam nach 63,0 SekundenÖffnen Sie den CapSkip Monitor und versuchen Sie es erneut
ApiException, deren Nachricht ERROR_CAPTCHA_UNSOLVABLE enthältDie Challenge wurde nicht bestanden. Das SDK wirft den rohen Antworttext; den echten Fehler-Body der Abfrage habe ich nicht geprüftMit einem neuen Task erneut versuchen
ok true, aber die Seite sagt, die Prüfung sei fehlgeschlagenDas Formular wurde gesendet; die Website hat den Token abgelehnt, oft wegen eines abweichenden User-Agent oder eines zu alten TokensLesen Sie den Seitentext und fordern Sie einen neuen Token an
error busy, window closed, no widget on the pageDie eigenen Schutzprüfungen dieses HandlersWarten, erneut klicken (ein neues Seitenfenster öffnet sich) oder die Seitenadresse prüfen

FAQ

Warum nicht CapSkip aus dem renderer aufrufen?

Ein renderer in der sandbox hat kein require, das Node SDK kann dort also nicht geladen werden, und ein renderer, der Ihren Schlüssel hielte, würde ihn jedem Skript zeigen, das er lädt. Im main process bleibt der Schlüssel in einem Modul.

Kann die CapSkip-Seite auf einem Server statt auf dem PC des Nutzers laufen?

Ja, über Server mode, wie oben beschrieben. Nur CAPSKIP_HOST ändert sich, und der App-Code bleibt gleich.

Eine Electron-App, die an einem Captcha vorbeikommen will, muss nur den richtigen Prozess fragen: Der main process ruft CapSkip auf, der renderer zeigt das Ergebnis, und der User-Agent wird umgestellt, bevor das Formular rausgeht. Die reine Node.js-Variante ohne Browser-Hülle finden Sie im Leitfaden zu Turnstile in Node.js. Da CapSkip eine Captcha-Umgehung ist, die auf Ihrem eigenen PC läuft, kostet ein erneuter Versuch mit einem abgelehnten Token nichts extra.