Electron CAPTCHA: Main Process’ten Turnstile Çözme

Bir Electron uygulamasından CAPTCHA çözmek için işi main process içinde tutun. Sayfayı bir BrowserWindow içinde yükleyin, sitekey değerini webContents.executeJavaScript ile okuyun, capskip Node SDK’sı ile CapSkip’ten bir token isteyin, pencereyi çözücünün bildirdiği User-Agent’a geçirin, token’ı gizli alana yazın ve formu gönderin. Bu electron captcha kılavuzu, kendi sitesine widget eklemek değil, bir Electron uygulamasının içinden Turnstile widget’ını geçmesi gereken geliştirici içindir. Renderer işi IPC üzerinden ister ve API key’i hiçbir zaman görmez. Her token şuradan gelir: CapSkip Turnstile çözücü sahibi olduğunuz bir Windows bilgisayarında çalışır.
Neye ihtiyacınız var
- CapSkip kurulu ve 127.0.0.1:8080 adresini dinleyen Local mode ile çalışan bir Windows bilgisayarı; adımlar kurulum kılavuzu içinde anlatılır.
- npm için Node.js 22.12 veya daha yenisi; electron paketinin bildirdiği alt sınır budur. capskip paketi Node.js 18 bildirir ve Electron 45.3.0 içindeki Node.js bunu karşılar: 24.22.2 bildirdi. Benim çalıştırmamda ilk başlatma, npm install’ın indirmediği Electron programını indirmek için 21,9 saniye harcadı.
- Otomatikleştirmenize izin verilen, Turnstile widget’lı bir sayfa.
- Uygulamanın çalıştığı yere uyan bir CapSkip adresi. Local mode yalnızca kendi bilgisayarına hizmet verir, Server mode ise ağınızı veya genel IP’nizi dinler; dağıtılan bir uygulamanın buna ihtiyacı vardır (son bölüme bakın).
Turnstile’ı seçtim, çünkü widget’ı token’ı düz bir gizli input içinde tutuyor ve sonucu çözücünün kullandığı User-Agent’ı taşıyor; oysa bir Electron sayfası farklı bir User-Agent ile yüklenir. Bu işin Electron’a ait kısmı bu uyuşmazlıktır.
Her şey Windows 11 üzerinde, Electron 45.3.0 (Chrome 156.0.8078.96) ve capskip 1.7.0 ile, yazdığım iki mock’a karşı çalıştı: biri CapSkip’i, diğeri Turnstile benzeri bir widget’ı olan bir iletişim sayfasını oynuyor. Token metni ve her site kuralı bana ait; gerçek CapSkip uygulamasına hiçbir görev gitmedi. Bir sarmalayıcı aynı main.js’i başlattı, açılan her pencereyi gizledi ve düğmeye script ile tıkladı; pencereler görünürken yapılan bir çalıştırma da aynı sonucu verdi. Uygulamayı hiç paketlemedim.
1. Adım: iki pencere, bir preload ve IPC köprüsü
Boş bir klasör oluşturun ve şu üç komutu çalıştırın. Sonuncusu, npm’in projeyi main.js üzerinden başlatmasını sağlar.
# npm install electron capskip npm init -y npm install electron capskip npm pkg set main=main.js
Uygulamanın iki pencereye ihtiyacı var. Biri kendi arayüzünüzü gösterir ve bir preload script alır. Diğeri CAPTCHA’lı sayfayı yükler ve hiçbir şey almaz; böylece o sayfadaki bir script’in main process’inize giden bir köprüsü olmaz. contextIsolation, nodeIntegration ve sandbox değerlerini açıkça ayarladım, ama Electron 45.3.0’da webPreferences verilmeyen bir pencere de aynı değerleri bildirdi ve Electron güvenlik kılavuzu bu varsayılanların 12, 5 ve 20. sürümlerden beri geçerli olduğunu belirtir.
// 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 burada bir kez oluşturulur; host, port ve key değerleri, SDK hiçbirini okumadığı için sizin okuduğunuz ortam değişkenlerinden gelir. Preload tek bir fonksiyon sunar, ipcRenderer’ın tamamını asla; invoke ise main process handler’ının döndürdüğü değerle çözülür.
// preload.js
const { contextBridge, ipcRenderer } = require("electron");
// Expose one narrow function, never ipcRenderer itself.
contextBridge.exposeInMainWorld("captcha", {
send: (email) => ipcRenderer.invoke("captcha:send", email),
});Arayüz script’i ayrı bir dosyada durur; böylece kendi Content-Security-Policy’si, güvenlik kılavuzunun önerdiği gibi yalnızca self kaynaklı script’lere izin verebilir.
<!-- 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;
});İki pencerede de require ve process tanımsızdı; window.captcha arayüz penceresinde tek bir anahtar (send) taşıyordu ve sayfa penceresinde tanımsızdı; API key de iki sayfanın HTML’inde yoktu. Aynı preload’a sahip ama başka bir sayfa gösteren bir deneme penceresi, handler’ın gönderen denetiminden reddedilmiş bir yanıt aldı; Electron güvenlik kılavuzu bunu ister.
2. Adım: çözen ve gönderen handler
Bunu main.js’in ilk bölümünün altına yapıştırın. Sayfayı yükler, sitekey değerini widget’ın data-sitekey özniteliğinden okur, solver.turnstile çağırır, bildirilen User-Agent’ı benimser, formu doldurur ve dönen sayfayı bekler.
// 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;
}
});Dört ayrıntı önemli. Birincisi, 1.7.0’da bir Turnstile yanıtı captchaId, code ve userAgent taşıyordu ve token alanı yoktu; yani token, code alanıdır. İkincisi, yanıttaki ok formun gönderildiğini söyler, sitenin token’ı kabul ettiğini değil: User-Agent adımı atlandığında mock’um uygulamaya ok yanıtı verdi ve sayfada Verification failed göründü; bu yüzden kendi sitenizin başarı metnine bakın. Üçüncüsü, Cloudflare’in render kılavuzu örtük render’ın cf-turnstile-response adlı görünmez bir input eklediğini, token’ların 300 saniye sonra sona erdiğini ve yalnızca bir kez doğrulandığını söyler. Sayfanız widget bitince bir callback çalıştırıyorsa, CapSkip API belgeleri onu token ile çalıştırmayı önerir; bunu test etmedim. Cloudflare’in gerçek widget script’ini, Cloudflare’in test için yayımladığı bir sitekey ile gizli bir pencerede bir kez yükledim ve input yüklemeden yaklaşık 2,5 saniye sonra belirdi; bu yüzden kod, alan eksikse onu oluşturur. O token’ı hiçbir yere göndermedim ve widget’ın sizin ayarladığınız bir değerin üzerine yazıp yazmadığını test etmedim. Dördüncüsü, JSON.stringify değerleri script’in içine yerleştirir ve tırnak ile ters eğik çizgi içeren bir e-posta mock’uma değişmeden ulaştı.
Zaman sınırları ve kapatılmış bir pencere
Turnstile, istemcinin varsayılan 120 saniyelik timeout değeriyle yoklar, reCAPTCHA’nın daha uzun değeriyle değil: defaultTimeout 5 ve recaptchaTimeout 300 iken hiç yanıt vermeyen bir mock 7,8 saniye sonra TimeoutException ile bitti. timeout seçeneği çağrı başınadır, saniye cinsindendir ve ben 60 yaptım. SDK süreyi yalnızca bir sonraki yoklama zamanı geldiğinde kontrol eder; bu yüzden hiç yanıt vermeyen bir mock, tıklamadan yanıta kadar 63,0 saniye sürdü. ipcRenderer.invoke’un kendi timeout değeri yoktur: hiç dönmeyen bir handler, izlemeyi 20 saniye sonra bıraktığımda çağrıyı beklemede bıraktı. SDK timeout değeri tek sınırınızdır.
SDK iptal edilemez. 4 saniyelik bir mock çözümünün 1,5. saniyesinde sayfa penceresini kapattığımda SDK yoklamaya devam etti ve yanıt 7,9. saniyede geldi. isDestroyed denetimi olmadan setUserAgent, TypeError: Object has been destroyed hatası verdi ve createSite olmadan sonraki her tıklama aynı şekilde başarısız oldu; ikisi birlikte varken bir sonraki tıklama yeni bir sayfa penceresi açtı ve başarılı oldu. Bir çözüm sürerken yapılan ikinci tıklama busy yanıtını aldı, çünkü tek bir sayfa penceresi iki işe hizmet edemez.
Bir handler içinde fırlatılan Error, renderer’a yalnızca bir mesaj olarak ulaşır: denemem code özelliği olan bir MyErr fırlattı ve renderer düz bir Error gördü. Bu yüzden handler her şeyi yakalar ve SDK istisnasının sınıf adını ile mesajını koruyan bir nesne döndürür.
3. Adım: sayfanın Content-Security-Policy’sinin neyi engellediği
executeJavaScript için Electron belgeleri Content-Security-Policy’den söz etmiyor, ben de test ettim. Mock sayfayı politikasız ve script-src self politikasıyla yükledim ve aynı denemeleri ana dünyada çalıştırdım.
| Deneme | Politika yok | Politika script-src self |
|---|---|---|
| Sayfanın kendi HTML’ine yazılmış satır içi script | Çalıştı | Engellendi |
| Sayfanın kendi origin’inden bir script dosyası | Çalıştı | Çalıştı |
| Gizli input’u ayarlayan executeJavaScript | Çalıştı | Çalıştı |
| Çalıştırılan kodun içinde eval() veya new Function() çağırmak | Çalıştı | EvalError |
| Çalıştırılan kodun eklediği, satır içi metinli bir script öğesi | Çalıştı | Engellendi |
| executeJavaScriptInIsolatedWorld içinde eval() | Çalıştı | Çalıştı |
executeJavaScript’e verdiğiniz kod çalışır, ama politika, onun dizelerden oluşturduğu her şeye yine uygulanır. Özellik atayın ve var olan fonksiyonları çağırın; politikanın buna bir sözü olmaz. 2. Adım’daki tam akış script-src sayfasına karşı geçti ve sayfanın kendi script dosyasını da engelleyen default-src none politikası, gizli input’un ayarlanmasına yine izin verdi.
4. Adım: sayfanın yüklendiği User-Agent
Bir Electron penceresi kendini bir Electron belirteciyle tanıtır: mock’um Chrome/156.0.8078.96 Electron/45.3.0 gördü. CapSkip API belgeleri, bir Turnstile token’ı gönderirken çözücünün User-Agent’ını göndermenizi söyler ve Node SDK onu seçmenize izin vermez: userAgent ve useragent ikisi de Unsupported parameters for Turnstile mesajıyla ValidationException verdi. Handler, sayfa yüklendikten sonra webContents.setUserAgent çağırır; mock’um bunu ayarlamanın beş yolu için şu sonuçları kaydetti.
| Ayarlama yolu | navigator.userAgent | İstek header’ı |
|---|---|---|
| Sayfa yüklendikten sonra webContents.setUserAgent | Hemen değişti, yeniden yükleme yok | Bir sonraki form gönderiminde çözücünün |
| loadURL öncesinde webContents.setUserAgent | Çözücünün | Sayfa yüklemesinde ve gönderimde çözücünün |
| Özel bir oturumda session.setUserAgent veya loadURL’un userAgent seçeneği | Çözücünün | İkisinde de çözücünün |
| Bir webRequest onBeforeSendHeaders hook’u | Hâlâ Electron dizesi | İkisinde de çözücünün |
Hook ayrı bir durum: navigator.userAgent okuyan bir sayfa script’i hâlâ Electron görür, sunucu ise başka bir şey görür. Uygulama User-Agent’ı ancak sayfa açıldıktan sonra öğrenir; bu yüzden yüklemeden sonraki çağrı uygundur. İsteklerimin hiçbiri sec-ch-ua header’ı taşımadı ve setUserAgent sonrasında navigator.userAgentData.brands listesi hâlâ Chromium 156 adını verdi; yani ikisi çelişiyor. Chromium, form gönderiminin kendisine Referer ve Origin ekledi. User-Agent denetimi mock’umun kuralıdır: gerçek bir siteyi test etmedim, bu yüzden birinin ikisini karşılaştırıp karşılaştırmadığı test edilmemiş durumda.
Çalıştırın ve dağıtılan uygulama için Server mode
Sayfa adresini ayarlayın, sonra uygulamayı başlatın. Yorum satırı yapılmış iki satır yalnızca Server mode içindir; CapSkip aynı bilgisayarda çalışırken onlara dokunmayın.
# 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 .
Dağıttığınız bir uygulama, 127.0.0.1 üzerinde bir CapSkip bulunacağına güvenemez. Ya her kullanıcı CapSkip’i kendi bilgisayarında Local mode ile çalıştırır ve kod olduğu gibi kalır, ya da CapSkip’i denetiminizdeki bir Windows makinesinde, ağınızı veya genel bir IP’yi dinlediği Server mode ile çalıştırırsınız ve CAPSKIP_HOST o makineyi adlandırır. CAPSKIP_PORT, 8080 dışındaki bir port için aynı işi görür. Server mode anahtarı CapSkip’in bağlantı ayarları içindedir, kurulum kılavuzu Server mode için CapSkip’in yönetici olarak çalışmasını şart koşar ve sabit bir adres uygulamayı hep aynı yere yönlendirir.
Üç uyarı daha var. CapSkip, Server mode başladığında portunu her adrese açar; bu yüzden onu beklediğiniz makinelerle sınırlamak için diğerleri için bir Windows Firewall engelleme kuralı ekleyin ve API Key Validation’ı açın. SDK, TLS seçeneği olmayan bir http adresi oluşturur; bu yüzden bir LAN veya VPN dışında key düz metin olarak gider. Ayrıca dağıttığınız bir uygulamanın içindeki key, uygulamayı çalıştıran herkes tarafından okunabilir; bu yüzden onu herkese açık sayın. Son ikisi bir test değil, SDK kaynağı hakkındaki yorumumdur.
Yaygın hatalar
mock olarak işaretli satırlar, mock’umun gerçek SDK üzerinden döndürdükleridir; gerisi CapSkip belgelerini izler.
| Handler’dan gelen yanıt | Neden | Düzeltme |
|---|---|---|
| ERROR_KEY_DOES_NOT_EXIST ile ApiException (mock) | API Key Validation açık ve gönderilen key yanlış. CAPSKIP_API_KEY yoksa SDK capskip gönderir | CAPSKIP_API_KEY ayarlayın |
| connect ECONNREFUSED ile NetworkException (mock port) | O host ve portu hiçbir şey dinlemiyor | CapSkip’i başlatın veya CAPSKIP_HOST ile portu düzeltin |
| timeout 60 exceeded ile TimeoutException (mock) | Çağrı timeout süresi içinde token gelmedi; yanıt 63,0. saniyede geldi | CapSkip Monitor’ü açın, sonra yeniden deneyin |
| Mesajı ERROR_CAPTCHA_UNSOLVABLE içeren ApiException | Challenge geçilemedi. SDK ham yanıt metnini fırlatır; gerçek yoklama hata gövdesini kontrol etmedim | Yeni bir görevle yeniden deneyin |
| ok true, ama sayfa kontrolün başarısız olduğunu söylüyor | Form gönderildi; site token’ı reddetti, çoğu zaman User-Agent veya yaş uyuşmazlığı yüzünden | Sayfa metnini okuyun ve yeni bir token isteyin |
| error busy, window closed, no widget on the page | Bu handler’ın kendi korumaları | Bekleyin, yeniden tıklayın (yeni bir sayfa penceresi açılır) veya sayfa adresini kontrol edin |
FAQ
CapSkip neden renderer’dan çağrılmıyor?
Sandbox içindeki bir renderer’da require yoktur, bu yüzden Node SDK orada yüklenemez ve key’inizi tutan bir renderer, yüklediği her script’e onu gösterir. Main process içinde key tek bir modülde kalır.
CapSkip tarafı, kullanıcının bilgisayarı yerine bir sunucuda çalışabilir mi?
Evet, yukarıda anlatıldığı gibi Server mode ile. Yalnızca CAPSKIP_HOST değişir, uygulama kodu aynı kalır.
CAPTCHA’yı geçmesi gereken bir Electron uygulamasının yalnızca doğru işleme sorması yeter: main process CapSkip’i çağırır, renderer sonucu gösterir ve form gitmeden önce User-Agent değiştirilir. Tarayıcı kabuğu olmayan düz Node.js sürümü için Node.js’te Turnstile kılavuzuna bakın. CapSkip kendi bilgisayarınızda çalışan bir captcha atlatma aracı olduğundan, reddedilen bir token’ı yeniden denemek ek bir maliyet getirmez.
