Капча в Electron: как решить Turnstile из main process

Чтобы решить капчу из приложения Electron, держите всю работу в main process. Загрузите страницу в BrowserWindow, прочитайте sitekey через webContents.executeJavaScript, запросите токен у CapSkip с помощью Node SDK capskip, переключите окно на User-Agent, который сообщает решатель, запишите токен в скрытое поле и отправьте форму. Это руководство по electron captcha адресовано разработчику, которому нужно пройти виджет Turnstile изнутри приложения Electron, а не добавить его на собственный сайт. Renderer запрашивает задание через IPC и никогда не видит API key. Каждый токен приходит от решателя CapSkip для Turnstile на ПК с Windows, который принадлежит вам.
Что понадобится
- ПК с Windows и установленным CapSkip (см. руководство по настройке ), запущенным в Local mode, который слушает 127.0.0.1:8080.
- Node.js 22.12 или новее для npm: это нижняя граница, которую объявляет пакет electron. Пакет capskip объявляет Node.js 18, и Node.js внутри Electron 45.3.0 этому требованию отвечает: он сообщил версию 24.22.2. В моём запуске первый старт потратил 21.9 секунды на загрузку программы Electron, которую npm install не скачал.
- Страница с виджетом Turnstile, которую вам разрешено автоматизировать.
- Адрес для CapSkip, подходящий для того места, где работает приложение. Local mode обслуживает только свой собственный ПК, а Server mode слушает вашу сеть или публичный IP, что нужно поставляемому приложению (см. последний раздел).
Я выбрал Turnstile, потому что его виджет хранит токен в обычном скрытом поле, а в его результате указан User-Agent, который использовал решатель, тогда как страница в Electron загружается с другим. Это расхождение и есть та часть задачи, которая относится именно к Electron.
Всё выполнялось на Windows 11 с Electron 45.3.0 (Chrome 156.0.8078.96) и capskip 1.7.0, против двух имитаций, которые я написал: одна изображает CapSkip, другая изображает страницу контактов с виджетом, похожим на Turnstile. Текст токена и все правила сайта мои, а настоящее приложение CapSkip не получило ни одного задания. Обёртка запускала тот же main.js, скрывала каждое окно при открытии и нажимала кнопку скриптом; один прогон с видимыми окнами дал тот же результат. Приложение я не упаковывал.
Шаг 1: два окна, preload и мост IPC
Создайте пустую папку и выполните эти три команды. Последняя заставляет npm запускать проект из main.js.
# npm install electron capskip npm init -y npm install electron capskip npm pkg set main=main.js
Приложению нужны два окна. Одно показывает ваш собственный интерфейс и получает скрипт preload. Другое загружает страницу с капчей и не получает ничего, поэтому у скрипта на этой странице нет моста к вашему main process. Я задал contextIsolation, nodeIntegration и sandbox явно, но окно без webPreferences в Electron 45.3.0 сообщило те же значения, а в руководстве по безопасности Electron указано, что эти значения по умолчанию появились в версиях 12, 5 и 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 создаётся один раз, здесь же, а его хост, порт и ключ берутся из переменных окружения, которые вы читаете сами, потому что SDK не читает ни одной. Preload открывает одну-единственную функцию, а не весь ipcRenderer, и invoke возвращает то, что вернёт обработчик в 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),
});Скрипт интерфейса лежит в отдельном файле, поэтому собственная Content-Security-Policy окна может разрешать скрипты только из self, как советует руководство по безопасности.
<!-- 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;
});В обоих окнах require и process были не определены; window.captcha содержал один ключ, send, в окне интерфейса и был не определён в окне страницы; а API key не появился в HTML ни одной из страниц. Окно-проба с тем же preload, но с другой страницей получило отказ от проверки отправителя в обработчике, которой требует руководство по безопасности Electron.
Шаг 2: обработчик, который решает и отправляет
Вставьте это ниже первой части main.js. Код загружает страницу, читает sitekey из атрибута data-sitekey виджета, вызывает solver.turnstile, принимает сообщённый User-Agent, заполняет форму и ждёт страницу, которая придёт в ответ.
// 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;
}
});Важны четыре детали. Во-первых, в 1.7.0 ответ Turnstile содержал captchaId, code и userAgent и не содержал поля token, поэтому токеном служит code. Во-вторых, ответ ok означает, что форма отправлена, а не то, что сайт принял токен: при пропущенном шаге с User-Agent моя имитация ответила приложению ok, а на странице появилось Verification failed, поэтому ищите текст успеха именно вашего сайта. В-третьих, в руководстве по рендерингу Cloudflare сказано, что неявный рендеринг добавляет невидимое поле с именем cf-turnstile-response, а токены истекают через 300 секунд и проходят проверку один раз. Если на вашей странице по завершении виджета выполняется функция обратного вызова, документация CapSkip API советует запускать её с токеном; я этого не проверял. Один раз я загрузил настоящий скрипт виджета Cloudflare в скрытом окне с sitekey, который Cloudflare публикует для тестов, и поле появилось примерно через 2.5 секунды после загрузки, поэтому код создаёт поле, если его нет. Этот токен я нигде не отправлял и не проверял, перезаписывает ли виджет значение, которое вы задали. В-четвёртых, JSON.stringify встраивает значения в скрипт, и email с кавычками и обратной косой чертой дошёл до моей имитации без изменений.
Ограничения по времени и закрытое окно
Turnstile опрашивает с таймаутом клиента по умолчанию, 120 секунд, а не с более длинным таймаутом reCAPTCHA: при defaultTimeout 5 и recaptchaTimeout 300 имитация, которая так и не ответила, завершилась TimeoutException через 7.8 секунды. Параметр timeout задаётся для каждого вызова, в секундах, и я поставил 60. SDK проверяет срок только тогда, когда подходит время следующего опроса, поэтому имитация, которая так и не ответила, потратила 63.0 секунды от нажатия до ответа. У ipcRenderer.invoke нет собственного таймаута: обработчик, который так и не вернулся, оставил вызов в ожидании, когда я перестал наблюдать через 20 секунд. Единственным вашим ограничением остаётся таймаут SDK.
SDK нельзя отменить. Когда я закрыл окно страницы через 1.5 секунды после начала 4-секундного решения на имитации, SDK продолжил опрос, и ответ пришёл на 7.9 секунде. Без проверки isDestroyed setUserAgent выбрасывал TypeError: Object has been destroyed, а без createSite каждый следующий клик заканчивался так же; с обоими окно страницы открывалось заново, и следующий клик проходил успешно. Второй клик во время решения получал ответ busy, поскольку одно окно страницы не может обслуживать два задания.
Error, выброшенный внутри обработчика, доходит до renderer только как сообщение: моя проба выбрасывала MyErr со свойством code, а renderer увидел обычный Error. Поэтому обработчик перехватывает всё и возвращает объект, в котором сохранены имя класса и сообщение исключения SDK.
Шаг 3: что блокирует Content-Security-Policy страницы
В документации Electron по executeJavaScript Content-Security-Policy не упоминается, поэтому я это проверил. Я загрузил страницу-имитацию без политики и с политикой script-src self и запустил те же пробы в основном мире.
| Проба | Без политики | Политика script-src self |
|---|---|---|
| Встроенный скрипт, написанный в собственном HTML страницы | Выполнился | Заблокирован |
| Файл скрипта с того же источника, что и страница | Выполнился | Выполнился |
| executeJavaScript, задающий скрытое поле | Сработало | Сработало |
| Вызов eval() или new Function() внутри выполняемого кода | Сработало | EvalError |
| Элемент script со встроенным текстом, который добавляет выполняемый код | Выполнился | Заблокирован |
| eval() в executeJavaScriptInIsolatedWorld | Сработало | Сработало |
Код, который вы передаёте в executeJavaScript, выполняется, но политика всё равно действует на всё, что он собирает из строк. Задавайте свойства и вызывайте существующие функции, и политике нечего сказать. Весь поток из шага 2 прошёл на странице со script-src, а политика default-src none, которая заблокировала даже собственный файл скрипта страницы, всё равно позволила задать скрытое поле.
Шаг 4: User-Agent, с которым загружается страница
Окно Electron представляется токеном Electron: моя имитация увидела Chrome/156.0.8078.96 Electron/45.3.0. В документации CapSkip API сказано отправлять User-Agent решателя при отправке токена Turnstile, а Node SDK не позволяет его выбрать: и userAgent, и useragent вызывали ValidationException с Unsupported parameters for Turnstile. Обработчик вызывает webContents.setUserAgent после загрузки страницы; моя имитация записала такие результаты для пяти способов его задать.
| Способ задания | navigator.userAgent | Заголовок запроса |
|---|---|---|
| webContents.setUserAgent после загрузки страницы | Меняется сразу, без перезагрузки | Как у решателя при следующей отправке формы |
| webContents.setUserAgent до loadURL | Как у решателя | Как у решателя при загрузке страницы и при отправке |
| session.setUserAgent в собственной сессии или параметр userAgent у loadURL | Как у решателя | Как у решателя в обоих случаях |
| Хук webRequest onBeforeSendHeaders | По-прежнему строка Electron | Как у решателя в обоих случаях |
Хук выбивается из ряда: скрипт страницы, читающий navigator.userAgent, по-прежнему видит Electron, а сервер видит другое значение. Приложение узнаёт User-Agent только после открытия страницы, поэтому вызов после загрузки подходит. Ни один из моих запросов не нёс заголовок sec-ch-ua, а после setUserAgent список navigator.userAgentData.brands по-прежнему называл Chromium 156, так что они расходятся. Chromium сам добавил Referer и Origin к отправке формы. Проверка User-Agent относится к правилам моей имитации: я не тестировал ни один настоящий сайт, поэтому неизвестно, сравнивает ли их какой-нибудь настоящий сайт.
Запуск и Server mode для поставляемого приложения
Задайте адрес страницы и запустите приложение. Две закомментированные строки нужны только для Server mode; не трогайте их, пока CapSkip работает на том же ПК.
# 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 .
Поставляемое приложение не может рассчитывать, что на 127.0.0.1 есть CapSkip. Либо каждый пользователь запускает CapSkip в Local mode на своём ПК, и код остаётся прежним, либо вы запускаете CapSkip на подконтрольной вам машине с Windows в Server mode, где он слушает вашу сеть или публичный IP, а CAPSKIP_HOST указывает на эту машину. CAPSKIP_PORT делает то же для порта, отличного от 8080. Раздел Настройки подключения содержит переключатель. Руководство по настройке сообщает, что Server mode требует запускать CapSkip от имени администратора, а статический адрес позволяет приложению всегда обращаться по одному и тому же адресу.
Далее три предостережения. При запуске Server mode CapSkip открывает свой порт для всех адресов, поэтому, чтобы оставить его только для ожидаемых машин, добавьте блокирующее правило Windows Firewall для остальных и включите API Key Validation. SDK строит адрес http без параметра TLS, поэтому за пределами LAN или VPN ключ передаётся открытым текстом. А ключ внутри распространяемого приложения может прочитать любой, кто его запускает, так что считайте его публичным. Последние два пункта получены из моего чтения исходного кода SDK, а не из теста.
Частые ошибки
Строки с пометкой «имитация» показывают то, что моя имитация вернула через настоящий SDK; остальные следуют документации CapSkip.
| Ответ обработчика | Причина | Исправить |
|---|---|---|
| ApiException с ERROR_KEY_DOES_NOT_EXIST (имитация) | API Key Validation включена, а отправленный ключ неверен. Без CAPSKIP_API_KEY SDK отправляет capskip | Задайте CAPSKIP_API_KEY |
| NetworkException с connect ECONNREFUSED (порт имитации) | По этому хосту и порту никто не слушает | Запустите CapSkip или исправьте CAPSKIP_HOST и порт |
| TimeoutException с timeout 60 exceeded (имитация) | Токен не получен за время таймаута вызова; ответ пришёл на 63.0 секунде | Откройте CapSkip Monitor и повторите попытку |
| ApiException, в сообщении которого есть ERROR_CAPTCHA_UNSOLVABLE | Проверка не пройдена. SDK выбрасывает необработанный текст ответа; настоящее тело ошибки опроса я не проверял | Повторите с новым заданием |
| ok true, но страница сообщает, что проверка не пройдена | Форма ушла; сайт отклонил токен, часто из-за несовпадения User-Agent или слишком старого токена | Прочитайте текст страницы и запросите новый токен |
| error busy, окно закрыто, на странице нет виджета | Собственные проверки этого обработчика | Подождите, нажмите снова (откроется новое окно страницы) или проверьте адрес страницы |
FAQ
Почему не вызывать CapSkip из renderer?
В renderer с песочницей нет require, поэтому Node SDK не может там загрузиться, а renderer, хранящий ваш ключ, показывал бы его каждому загружаемому скрипту. В main process ключ остаётся в одном модуле.
Может ли сторона CapSkip работать на сервере, а не на ПК пользователя?
Да, через Server mode, как описано выше. Меняется только CAPSKIP_HOST, а код приложения остаётся прежним.
Приложению Electron, которому нужно пройти капчу, достаточно обратиться к правильному процессу: main вызывает CapSkip, renderer показывает результат, а User-Agent переключается до отправки формы. Версию на чистом Node.js без оболочки браузера смотрите в руководстве по Turnstile в Node.js. CapSkip работает на вашем собственном ПК, так что обход капчи не требует доплат за каждое решение, поэтому повтор после отклонённого токена ничего не стоит.
