Electron CAPTCHA: Memecahkan Turnstile dari Main Process

Untuk memecahkan CAPTCHA dari aplikasi Electron, simpan pekerjaannya di main process. Muat halaman di BrowserWindow, baca sitekey dengan webContents.executeJavaScript, minta token ke CapSkip lewat capskip Node SDK, ubah window ke User-Agent yang dilaporkan pemecah, tulis token ke field tersembunyi, lalu kirim form. Panduan electron captcha ini ditujukan bagi developer yang harus melewati widget Turnstile dari dalam aplikasi Electron, bukan menambahkannya ke situs sendiri. Renderer meminta pekerjaan lewat IPC dan tidak pernah melihat API key. Setiap token berasal dari pemecah Turnstile CapSkip yang berjalan di PC Windows milik Anda.
Apa yang Anda butuhkan
- PC Windows dengan CapSkip yang dipasang sesuai panduan penyiapan dan dijalankan dalam Local mode, yang mendengarkan di 127.0.0.1:8080.
- Node.js 22.12 atau lebih baru untuk npm, batas minimum yang dinyatakan paket electron. Paket capskip menyatakan Node.js 18, yang dipenuhi oleh Node.js di dalam Electron 45.3.0: versinya 24.22.2. Pada eksekusi saya, start pertama menghabiskan 21,9 detik untuk mengunduh program Electron, yang tidak diambil oleh npm install.
- Halaman dengan widget Turnstile yang boleh Anda otomatisasi.
- Alamat untuk CapSkip yang sesuai dengan tempat aplikasi berjalan. Local mode hanya melayani PC-nya sendiri, sedangkan Server mode mendengarkan di jaringan atau IP publik Anda, yang dibutuhkan aplikasi yang didistribusikan (lihat bagian terakhir).
Saya memilih Turnstile karena widgetnya menyimpan token di input tersembunyi biasa, dan hasilnya membawa User-Agent yang dipakai pemecah, sementara halaman di Electron dimuat dengan User-Agent yang berbeda. Perbedaan itulah bagian pekerjaan ini yang menjadi urusan Electron.
Semuanya berjalan di Windows 11 dengan Electron 45.3.0 (Chrome 156.0.8078.96) dan capskip 1.7.0, terhadap dua mock buatan saya: satu berperan sebagai CapSkip dan satu lagi sebagai halaman kontak dengan widget berbentuk Turnstile. Teks token dan semua aturan situs adalah buatan saya, dan aplikasi CapSkip yang asli tidak menerima task apa pun. Sebuah wrapper menjalankan main.js yang sama, menyembunyikan setiap window saat terbuka, dan mengeklik tombol dari skrip; satu eksekusi dengan window terlihat memberi hasil yang sama. Saya tidak pernah mengemas aplikasinya.
Langkah 1: dua window, preload, dan jembatan IPC
Buat folder kosong dan jalankan tiga perintah ini. Perintah terakhir membuat npm menjalankan proyek dari main.js.
# npm install electron capskip npm init -y npm install electron capskip npm pkg set main=main.js
Aplikasi ini butuh dua window. Satu menampilkan antarmuka Anda sendiri dan mendapat skrip preload. Satunya memuat halaman dengan CAPTCHA dan tidak mendapat apa pun, sehingga skrip di halaman itu tidak punya jembatan ke main process Anda. Saya mengatur contextIsolation, nodeIntegration, dan sandbox secara eksplisit, tetapi window tanpa webPreferences di Electron 45.3.0 melaporkan nilai yang sama, dan panduan keamanan Electron menyebut bahwa nilai bawaan itu berlaku sejak versi 12, 5, dan 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 dibuat satu kali, di sini, dan host, port, serta key-nya berasal dari environment variable yang Anda baca sendiri, karena SDK tidak membaca satu pun. Preload hanya mengekspos satu fungsi, tidak pernah seluruh ipcRenderer, dan invoke menghasilkan apa pun yang dikembalikan handler di main process.
// preload.js
const { contextBridge, ipcRenderer } = require("electron");
// Expose one narrow function, never ipcRenderer itself.
contextBridge.exposeInMainWorld("captcha", {
send: (email) => ipcRenderer.invoke("captcha:send", email),
});Skrip antarmuka berada di file terpisah, sehingga Content-Security-Policy miliknya sendiri bisa mengizinkan skrip dari self saja, seperti yang disarankan panduan keamanan.
<!-- 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;
});Di kedua window, require dan process tidak terdefinisi; window.captcha berisi satu key, send, di window antarmuka dan tidak terdefinisi di window halaman; dan API key tidak muncul di HTML kedua halaman. Sebuah window probe yang memakai preload yang sama tetapi menampilkan halaman lain mendapat balasan penolakan dari pemeriksaan pengirim di handler, yang diminta oleh panduan keamanan Electron.
Langkah 2: handler yang memecahkan dan mengirim
Tempel kode ini di bawah bagian pertama main.js. Kode ini memuat halaman, membaca sitekey dari atribut data-sitekey pada widget, memanggil solver.turnstile, memakai User-Agent yang dilaporkan, mengisi form, dan menunggu halaman yang datang sesudahnya.
// 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;
}
});Ada empat hal yang penting. Pertama, di 1.7.0 jawaban Turnstile berisi captchaId, code, dan userAgent tanpa field token, jadi tokennya adalah code. Kedua, balasan ok berarti form sudah terkirim, bukan berarti situs menerima token: dengan langkah User-Agent dilewati, mock saya menjawab ok ke aplikasi dan Verification failed di halaman, jadi cari teks sukses dari situs Anda sendiri. Ketiga, Cloudflare menulis di panduan rendering bahwa rendering implisit menambahkan input tak terlihat bernama cf-turnstile-response, dan bahwa token kedaluwarsa setelah 300 detik serta hanya valid satu kali. Jika halaman Anda menjalankan callback saat widget selesai, dokumentasi API CapSkip menyarankan menjalankannya dengan token; saya tidak mengujinya. Saya memuat skrip widget asli dari Cloudflare satu kali di window tersembunyi, dengan sitekey yang dipublikasikan Cloudflare untuk pengujian, dan input itu muncul sekitar 2,5 detik setelah dimuat, jadi kode membuat field-nya bila belum ada. Saya tidak mengirim token itu ke mana pun dan tidak menguji apakah widget menimpa nilai yang Anda atur. Keempat, JSON.stringify memasukkan nilai ke dalam skrip, dan email yang berisi tanda kutip dan backslash sampai ke mock saya tanpa berubah.
Batas waktu dan window yang ditutup
Turnstile melakukan polling dengan timeout bawaan klien sebesar 120 detik, bukan yang lebih panjang untuk reCAPTCHA: dengan defaultTimeout 5 dan recaptchaTimeout 300, mock yang tidak pernah menjawab berakhir dengan TimeoutException setelah 7,8 detik. Opsi timeout berlaku per panggilan, dalam detik, dan saya mengaturnya ke 60. SDK memeriksa batas waktu hanya ketika polling berikutnya jatuh tempo, sehingga mock yang tidak pernah menjawab memakan 63,0 detik dari klik sampai balasan. ipcRenderer.invoke tidak punya timeout sendiri: handler yang tidak pernah kembali membuat panggilan tetap menggantung ketika saya berhenti mengamati setelah 20 detik. Timeout SDK adalah satu-satunya batas Anda.
SDK tidak bisa dibatalkan. Ketika saya menutup window halaman pada detik ke 1,5 dari penyelesaian mock selama 4 detik, SDK terus melakukan polling dan balasan datang pada detik ke 7,9. Tanpa pemeriksaan isDestroyed, setUserAgent melempar TypeError: Object has been destroyed, dan tanpa createSite setiap klik berikutnya gagal dengan cara yang sama; dengan keduanya, klik berikutnya membuka window halaman baru dan berhasil. Klik kedua saat penyelesaian sedang berjalan mendapat balasan busy, karena satu window halaman tidak bisa melayani dua pekerjaan.
Error yang dilempar di dalam handler sampai ke renderer hanya sebagai pesan: probe saya melempar MyErr dengan properti code, dan renderer hanya melihat Error biasa. Karena itu handler menangkap semuanya dan mengembalikan objek yang menyimpan nama class dan pesan dari exception SDK.
Langkah 3: apa yang diblokir Content-Security-Policy halaman
Dokumentasi Electron untuk executeJavaScript tidak menyebut Content-Security-Policy, jadi saya mengujinya. Saya memuat halaman mock tanpa kebijakan dan dengan kebijakan script-src self, lalu menjalankan probe yang sama di main world.
| Probe | Tanpa kebijakan | Kebijakan script-src self |
|---|---|---|
| Skrip inline yang ditulis di HTML halaman itu sendiri | Berjalan | Diblokir |
| File skrip dari origin halaman itu sendiri | Berjalan | Berjalan |
| executeJavaScript mengatur input tersembunyi | Berhasil | Berhasil |
| Memanggil eval() atau new Function() di dalam kode yang dijalankan | Berhasil | EvalError |
| Elemen script dengan teks inline yang ditambahkan oleh kode yang dijalankan | Berjalan | Diblokir |
| eval() di executeJavaScriptInIsolatedWorld | Berhasil | Berhasil |
Kode yang Anda berikan ke executeJavaScript memang berjalan, tetapi kebijakan tetap berlaku untuk apa pun yang dibangunnya dari string. Atur properti dan panggil fungsi yang sudah ada, dan kebijakan tidak ikut campur. Alur lengkap dari Langkah 2 lolos terhadap halaman script-src, dan kebijakan default-src none, yang juga memblokir file skrip milik halaman itu sendiri, tetap membiarkan input tersembunyi diatur.
Langkah 4: User-Agent saat halaman dimuat
Window Electron mengenalkan dirinya dengan token Electron: mock saya melihat Chrome/156.0.8078.96 Electron/45.3.0. Dokumentasi API CapSkip menyuruh mengirim User-Agent milik pemecah saat Anda mengirim token Turnstile, dan Node SDK tidak memberi Anda pilihan untuk itu: userAgent dan useragent sama-sama memunculkan ValidationException dengan Unsupported parameters for Turnstile. Handler memanggil webContents.setUserAgent setelah halaman dimuat; mock saya mencatat hasil berikut untuk lima cara mengaturnya.
| Cara mengaturnya | navigator.userAgent | Header request |
|---|---|---|
| webContents.setUserAgent setelah halaman dimuat | Berubah seketika, tanpa reload | Milik pemecah pada pengiriman form berikutnya |
| webContents.setUserAgent sebelum loadURL | Milik pemecah | Milik pemecah pada pemuatan halaman dan pengiriman form |
| session.setUserAgent pada session kustom, atau opsi userAgent dari loadURL | Milik pemecah | Milik pemecah pada keduanya |
| Hook webRequest onBeforeSendHeaders | Masih string Electron | Milik pemecah pada keduanya |
Hook ini yang berbeda dari yang lain: skrip halaman yang membaca navigator.userAgent masih melihat Electron, sementara server melihat yang lain. Aplikasi baru mengetahui User-Agent setelah halaman terbuka, sehingga pemanggilan setelah dimuat paling cocok. Tidak satu pun request saya membawa header sec-ch-ua, dan setelah setUserAgent daftar navigator.userAgentData.brands masih menyebut Chromium 156, jadi keduanya tidak sama. Chromium menambahkan Referer dan Origin pada pengiriman form itu sendiri. Pemeriksaan User-Agent adalah aturan dari mock saya: saya tidak menguji situs sungguhan, jadi belum diuji apakah ada situs yang membandingkan keduanya.
Jalankan, dan Server mode untuk aplikasi yang didistribusikan
Atur alamat halaman, lalu jalankan aplikasi. Dua baris yang dikomentari hanya untuk Server mode; biarkan saja selama CapSkip berjalan di PC yang sama.
# 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 .
Aplikasi yang Anda distribusikan tidak bisa mengandalkan 127.0.0.1 yang menjalankan CapSkip. Entah setiap pengguna menjalankan CapSkip dalam Local mode di PC mereka sendiri dan kodenya tetap seperti ini, atau Anda menjalankan CapSkip di mesin Windows yang Anda kendalikan dalam Server mode, tempat CapSkip mendengarkan di jaringan atau IP publik Anda, dan CAPSKIP_HOST menyebut mesin itu. CAPSKIP_PORT melakukan hal yang sama untuk port selain 8080. Bagian pengaturan koneksi memuat tombol pengalihnya, panduan penyiapan menyatakan Server mode mengharuskan CapSkip berjalan sebagai administrator, dan alamat statis menjaga aplikasi tetap mengarah ke tempat yang sama.
Ada tiga peringatan. CapSkip membuka port-nya untuk semua alamat saat Server mode dimulai, jadi agar hanya mesin yang Anda harapkan yang bisa mengakses, tambahkan aturan blokir Windows Firewall untuk yang lain, dan aktifkan API Key Validation. SDK membangun alamat http tanpa opsi TLS, jadi di luar LAN atau VPN key dikirim sebagai teks biasa. Dan key di dalam aplikasi yang Anda distribusikan bisa dibaca oleh siapa pun yang menjalankannya, jadi anggaplah key itu publik. Dua yang terakhir adalah pembacaan saya atas source SDK, bukan hasil pengujian.
Kesalahan umum
Baris yang ditandai mock adalah yang dikembalikan mock saya melalui SDK yang asli; sisanya mengikuti dokumentasi CapSkip.
| Balasan dari handler | Penyebab | Perbaiki |
|---|---|---|
| ApiException dengan ERROR_KEY_DOES_NOT_EXIST (mock) | API Key Validation aktif dan key yang dikirim salah. Tanpa CAPSKIP_API_KEY, SDK mengirim capskip | Atur CAPSKIP_API_KEY |
| NetworkException dengan connect ECONNREFUSED (port mock) | Tidak ada yang mendengarkan di host dan port itu | Jalankan CapSkip, atau perbaiki CAPSKIP_HOST dan port-nya |
| TimeoutException dengan timeout 60 exceeded (mock) | Tidak ada token dalam batas waktu panggilan; balasan datang pada detik ke 63,0 | Buka CapSkip Monitor, lalu coba lagi |
| ApiException yang pesannya berisi ERROR_CAPTCHA_UNSOLVABLE | Tantangan tidak berhasil dilewati. SDK melempar teks balasan mentah; saya tidak memeriksa isi error poll yang asli | Coba lagi dengan task baru |
| ok true, tetapi halaman menyatakan pemeriksaan gagal | Form sudah terkirim; situs menolak token, sering karena User-Agent atau usia token tidak cocok | Baca teks halaman, dan minta token baru |
| error busy, window closed, no widget on the page | Pengaman milik handler ini sendiri | Tunggu, klik lagi (window halaman baru terbuka), atau periksa alamat halaman |
FAQ
Mengapa tidak memanggil CapSkip dari renderer?
Renderer yang di-sandbox tidak punya require, jadi Node SDK tidak bisa dimuat di sana, dan renderer yang menyimpan key Anda akan menampakkannya ke setiap skrip yang dimuatnya. Di main process, key tetap berada di satu modul.
Bisakah sisi CapSkip berjalan di server, bukan di PC pengguna?
Bisa, lewat Server mode, seperti dijelaskan di atas. Hanya CAPSKIP_HOST yang berubah, dan kode aplikasi tetap sama.
Aplikasi Electron yang perlu melewati CAPTCHA cukup meminta proses yang tepat: main process memanggil CapSkip, renderer menampilkan hasilnya, dan User-Agent diganti sebelum form dikirim. Untuk versi Node.js biasa tanpa cangkang browser, lihat panduan Turnstile di Node.js. Karena CapSkip adalah alat bypass captcha yang berjalan di PC Anda sendiri, mencoba ulang token yang ditolak tidak memerlukan biaya tambahan.
