Electron-Captcha: Turnstile im main process lösen

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.
| Probe | Keine Policy | Policy script-src self |
|---|---|---|
| Inline-Skript im eigenen HTML der Seite | Lief | Blockiert |
| Skriptdatei vom eigenen Origin der Seite | Lief | Lief |
| executeJavaScript setzt das versteckte Input | Funktionierte | Funktionierte |
| eval() oder new Function() im ausgeführten Code aufrufen | Funktionierte | EvalError |
| Ein script-Element mit Inline-Text, das der ausgeführte Code hinzufügt | Lief | Blockiert |
| eval() in executeJavaScriptInIsolatedWorld | Funktionierte | Funktionierte |
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 setzen | navigator.userAgent | Request-Header |
|---|---|---|
| webContents.setUserAgent nach dem Laden der Seite | Sofort geändert, ohne Neuladen | Der des Solvers beim nächsten Absenden des Formulars |
| webContents.setUserAgent vor loadURL | Der des Solvers | Der des Solvers beim Laden der Seite und beim Absenden |
| session.setUserAgent auf einer eigenen Session oder die Option userAgent von loadURL | Der des Solvers | Der des Solvers bei beiden |
| Ein webRequest-Hook onBeforeSendHeaders | Weiterhin der Electron-String | Der 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 Handlers | Ursache | Beheben |
|---|---|---|
| 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 capskip | CAPSKIP_API_KEY setzen |
| NetworkException mit connect ECONNREFUSED (mock port) | Nichts lauscht auf diesem Host und Port | Starten 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ält | Die Challenge wurde nicht bestanden. Das SDK wirft den rohen Antworttext; den echten Fehler-Body der Abfrage habe ich nicht geprüft | Mit einem neuen Task erneut versuchen |
| ok true, aber die Seite sagt, die Prüfung sei fehlgeschlagen | Das Formular wurde gesendet; die Website hat den Token abgelehnt, oft wegen eines abweichenden User-Agent oder eines zu alten Tokens | Lesen Sie den Seitentext und fordern Sie einen neuen Token an |
| error busy, window closed, no widget on the page | Die eigenen Schutzprüfungen dieses Handlers | Warten, 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.
