Electron 验证码:在主进程中识别 Turnstile

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

要在 Electron 应用里识别验证码,就把这项工作放在主进程中完成。在 BrowserWindow 里加载页面,用 webContents.executeJavaScript 读出 sitekey,通过 capskip Node SDK 向 CapSkip 要一个 token,把窗口切换成识别工具报告的 User-Agent,再把 token 写进隐藏字段并提交表单。这篇 electron captcha 指南写给需要在 Electron 应用内部通过 Turnstile 小组件的开发者,而不是给自己的网站添加小组件的人。渲染进程通过 IPC 请求这项任务,永远看不到 API key。每个 token 都来自 CapSkip Turnstile 识别工具 ,它运行在你自己拥有的 Windows PC 上。

你需要什么

  • 一台 Windows PC,已按 设置指南 所述安装好 CapSkip,并以 Local mode 运行,它监听 127.0.0.1:8080。
  • Node.js 22.12 或更高版本用于 npm,这是 electron 包声明的下限。capskip 包声明的是 Node.js 18,而 Electron 45.3.0 内置的 Node.js 满足这个要求:它报告的版本是 24.22.2。在我的运行中,第一次启动花了 21.9 秒下载 Electron 程序,npm install 并不会下载它。
  • 一个带有 Turnstile 小组件、你有权自动化操作的页面。
  • 一个适合应用运行位置的 CapSkip 地址。Local mode 只为它所在的这台 PC 服务,而 Server mode 会监听你的网络或公网 IP,发布出去的应用需要这种方式(见最后一节)。

我选择 Turnstile,是因为它的小组件把 token 保存在一个普通的隐藏 input 里,而且它的结果带有识别工具使用的 User-Agent,但 Electron 页面加载时用的是另一个。这个冲突正是这项工作中属于 Electron 的部分。

所有内容都在 Windows 11 上运行,使用 Electron 45.3.0(Chrome 156.0.8078.96)和 capskip 1.7.0,对着我写的两个模拟服务器:一个扮演 CapSkip,另一个扮演带有 Turnstile 形态小组件的联系页面。token 文本和每条站点规则都是我定的,真实的 CapSkip 应用没有收到任何任务。一个包装脚本启动同一个 main.js,在每个窗口打开时把它隐藏,并用脚本点击按钮;用可见窗口跑了一次,结果一致。我从未打包过这个应用。

第 1 步:两个窗口、一个 preload 脚本和 IPC 桥

新建一个空文件夹,运行下面这三条命令。最后一条让 npm start 从 main.js 启动项目。

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

应用需要两个窗口。一个显示你自己的界面,并带有 preload 脚本。另一个加载带 CAPTCHA 的页面,什么都不带,所以那个页面上的脚本没有通向你主进程的桥。我显式设置了 contextIsolation、nodeIntegration 和 sandbox,不过在 Electron 45.3.0 中,没有 webPreferences 的窗口报告的值是一样的,而 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 会以主进程处理程序返回的任何内容完成。

// 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 都是 undefined;window.captcha 在界面窗口里只有一个键 send,在页面窗口里是 undefined;API key 没有出现在任何一个页面的 HTML 里。一个使用相同 preload 但显示另一个页面的探测窗口,被处理程序的发送方检查拒绝并返回了拒绝的回复,Electron 安全指南也要求做这项检查。

第 2 步:识别并提交的处理程序

把下面的代码粘贴到 main.js 第一部分的后面。它加载页面,从小组件的 data-sitekey 属性读出 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 字段,所以 token 就是 code。第二,回复里的 ok 表示表单已提交,而不是站点接受了 token:跳过 User-Agent 步骤时,我的模拟服务器对应用回复了 ok,页面上却显示 Verification failed,所以要去找你自己站点的成功文本。第三,Cloudflare 的 渲染指南 说,隐式渲染会添加一个名为 cf-turnstile-response 的不可见 input,并且 token 300 秒后过期,只能验证一次。如果你的页面在小组件完成时会运行回调,CapSkip API 文档建议带着 token 去运行它;这一点我没有测试。我在一个隐藏窗口里加载过一次 Cloudflare 的真实小组件脚本,使用的是 Cloudflare 公布的测试用 sitekey,加载约 2.5 秒后 input 出现了,所以代码会在字段缺失时创建它。我没有把那个 token 提交到任何地方,也没有测试小组件是否会覆盖你设置的值。第四,JSON.stringify 把这些值构建进脚本,一个含有引号和反斜杠的邮箱原样到达了我的模拟服务器。

时间限制与关闭的窗口

Turnstile 按客户端默认的 120 秒超时轮询,而不是更长的 reCAPTCHA 超时:设置 defaultTimeout 为 5、recaptchaTimeout 为 300 时,一个始终不回答的模拟服务器在 7.8 秒后以 TimeoutException 结束。timeout 选项是按每次调用设置的,单位是秒,我设成了 60。SDK 只在下一次轮询到期时才检查截止时间,所以一个始终不回答的模拟服务器从点击到回复花了 63.0 秒。ipcRenderer.invoke 自己没有超时:一个始终不返回的处理程序,在我观察 20 秒后停止时,调用仍处于挂起状态。SDK 的超时是你唯一的限制。

SDK 无法取消。在一次 4 秒的模拟识别进行到 1.5 秒时,我关闭了页面窗口,SDK 仍在继续轮询,回复在 7.9 秒时才到。没有 isDestroyed 检查时,setUserAgent 会抛出 TypeError: Object has been destroyed,没有 createSite 时,之后的每次点击都会以同样方式失败;两者都有时,下一次点击会打开新的页面窗口并成功。识别期间的第二次点击得到的是 busy 回复,因为一个页面窗口不能同时处理两个任务。

在处理程序内部抛出的 Error 到达渲染进程时只剩下消息:我的探测抛出了带有 code 属性的 MyErr,渲染进程看到的却是普通的 Error。所以处理程序会捕获一切,并返回一个保留 SDK 异常类名和消息的对象。

第 3 步:页面的 Content-Security-Policy 会拦截什么

Electron 关于 executeJavaScript 的文档没有提到 Content-Security-Policy,所以我做了测试。我分别在没有策略和带有 script-src self 策略的情况下加载模拟页面,并在主世界中运行同样的探测。

探测项无策略策略 script-src self
页面自己的 HTML 中写的内联脚本已运行被阻止
来自页面同源的脚本文件已运行已运行
executeJavaScript 设置隐藏 input成功成功
在被执行的代码里调用 eval() 或 new Function()成功EvalError
由被执行的代码添加的、带内联文本的 script 元素已运行被阻止
executeJavaScriptInIsolatedWorld 中的 eval()成功成功

你交给 executeJavaScript 的代码会运行,但策略仍然适用于它用字符串构建出的任何东西。设置属性并调用现有函数,策略就管不着。第 2 步的完整流程在带 script-src 的页面上通过了,而 default-src none 策略连页面自己的脚本文件也拦截了,却仍然允许设置隐藏 input。

第 4 步:页面加载时使用的 User-Agent

Electron 窗口会用一个 Electron 标记来标识自己:我的模拟服务器看到的是 Chrome/156.0.8078.96 Electron/45.3.0。CapSkip API 文档说,提交 Turnstile token 时要发送识别工具的 User-Agent,而 Node SDK 不允许你选择它:userAgent 和 useragent 都会抛出 ValidationException,提示 Unsupported parameters for Turnstile。处理程序在页面加载之后调用 webContents.setUserAgent;我的模拟服务器记录了五种设置方式的这些结果。

设置方式navigator.userAgent请求头
页面加载后调用 webContents.setUserAgent立即改变,无需重新加载下一次提交表单时与识别工具的一致
loadURL 之前调用 webContents.setUserAgent与识别工具的一致页面加载和提交时都与识别工具的一致
自定义 session 上的 session.setUserAgent,或 loadURL 的 userAgent 选项与识别工具的一致两次都与识别工具的一致
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 运行在同一台 PC 上,就不要动它们。

# 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。要么每个用户在自己的 PC 上以 Local mode 运行 CapSkip,代码保持不变;要么你在自己掌控的一台 Windows 机器上以 Server mode 运行 CapSkip,它会监听你的网络或公网 IP,并由 CAPSKIP_HOST 指明那台机器。CAPSKIP_PORT 对 8080 以外的端口起同样的作用。 连接设置 里有这个开关,设置指南说明 Server mode 要求 CapSkip 以管理员身份运行,而使用固定地址能让应用始终指向同一个位置。

接下来是三条提醒。Server mode 启动时,CapSkip 会向所有地址开放它的端口,所以要把访问限制在你预期的机器上,就为其他机器添加一条 Windows Firewall 阻止规则,并开启 API Key Validation。SDK 构建的是一个没有 TLS 选项的 http 地址,所以一旦超出局域网或 VPN,密钥就会以明文传输。而且,你分发的应用里的密钥,任何运行它的人都能读到,所以要把它当作公开的。后两点是我对 SDK 源码的理解,不是测试结果。

常见错误

标为 mock 的行是我的模拟服务器通过真实 SDK 返回的内容;其余各行依据 CapSkip 文档。

处理程序的回复原因修复
ApiException,附带 ERROR_KEY_DOES_NOT_EXIST(mock)API Key Validation 已开启,而发送的密钥有误。没有 CAPSKIP_API_KEY 时,SDK 发送的是 capskip设置 CAPSKIP_API_KEY
NetworkException,附带 connect ECONNREFUSED(mock 端口)该主机和端口上没有任何程序在监听启动 CapSkip,或修正 CAPSKIP_HOST 和端口
TimeoutException,附带 timeout 60 exceeded(mock)在调用超时时间内没有拿到 token;回复在 63.0 秒时到达打开 CapSkip Monitor,然后重试
消息中含有 ERROR_CAPTCHA_UNSOLVABLE 的 ApiException没有通过挑战。SDK 抛出的是原始回复文本;我没有检查真实的轮询错误体用一个新任务重试
ok true,但页面显示检查失败表单已发出;站点拒绝了 token,常见原因是 User-Agent 或 token 存在时间不匹配读取页面文本,并重新获取一个新的 token
error busy, window closed, no widget on the page这个处理程序自己的防护等待后再点击一次(会打开一个新的页面窗口),或检查页面地址

常见问题

为什么不在渲染进程里调用 CapSkip?

沙盒化的渲染进程没有 require,所以 Node SDK 无法在那里加载,而且持有你密钥的渲染进程会把密钥暴露给它加载的每一个脚本。在主进程里,密钥只留在一个模块中。

CapSkip 这一侧能运行在服务器上,而不是用户的 PC 上吗?

可以,通过 Server mode,如上文所述。只有 CAPSKIP_HOST 需要改变,应用代码保持不变。

需要越过 CAPTCHA 的 Electron 应用,只需要找对进程:主进程调用 CapSkip,渲染进程显示结果,并在表单发出之前切换 User-Agent。如果你想要不带浏览器外壳的纯 Node.js 版本,请参阅 Node.js 版 Turnstile 指南。因为 CapSkip 是一款 验证码绕过 工具,运行在你自己的 PC 上,所以重试被拒绝的 token 不会产生额外费用。