Cap 社区生态指南:多语言/多框架库与不依赖官方 SDK 的令牌验证

原创2026-09-28 19:35:381,875 阅读
文章标签:网络安全应用安全后端

Cap 社区生态指南:多语言/多框架库与不依赖官方 SDK 的令牌验证

Cap 是一款开源、可自托管的 CAPTCHA 替代方案,官方推荐通过 Standalone Docker 容器运行,并提供 <cap-widget> Web Component 与 /siteverify 验证接口。社区围绕它发展出了覆盖 React、Angular、Vue、Java、Go、Python、.NET、PHP、Cloudflare Workers 等生态的第三方库,让你在没有官方服务器或不同语言栈下也能接入 Cap。读完本文,你将掌握社区库的分类与选择方法、它们相对官方路线的能力边界,以及完全不依赖任何 SDK、直接调用协议完成令牌签发与验证的实战方案。

官方运行路径与社区库出现的动机

在深入社区生态之前,先明确 Cap 的官方架构,这决定了社区库“补什么、缺什么”。

Cap 由两部分组成:

  1. 客户端 Widget:一个原生 Web Component(<cap-widget>),负责向后端请求挑战、在浏览器内用 WASM 求解 proof-of-work,并在通过后拿到令牌。它不依赖任何框架,可在任何现代浏览器中直接使用。
  2. 服务端:推荐 Cap Standalone(单容器、REST API + 管理面板),或 capjs-core(无状态、JWT 挑战签发与验证库)。

官方 Widget 是一个标准 Custom Element,理论上"哪里都能跑",因此社区 Widget 类库通常不是必需品,而是为了在 React/Vue 等框架中获得更顺手的开发体验。真正有价值的社区库集中在服务端:当你的后端不是官方支持的运行时(例如 Cloudflare Workers、Java、Go、.NET、PHP),或者不想跑 Docker 时,社区维护的服务器实现能让你用自己的语言验证 Cap 令牌。

从源码可以看到这条链路的关键点:

  • Widget 通过 data-cap-api-endpoint 属性定位你的实例,例如 https://<instance>/<site-key>/,在表单中自动注入隐藏的 cap-token 字段(默认字段名,见 widget/src/src/cap.js);
  • Standalone 的验证端点在 standalone/src/siteverify.js 实现,校验 secret 与 response 后,通过 GETDEL 原子地消费一次性令牌;
  • 签发端的 challenge / redeem 流程在 standalone/src/cap.js 中,底层调用 capjs-core 的 generateChallenge / validateChallenge。

任何语言的社区服务器,本质上都要实现这三件事:签发挑战 → 校验解 → 消费一次性令牌。

社区库生态总览

社区维护的库按用途分为四类,对应 Cap 集成的四个层次:

分类 定位 代表语言/框架
Widgets 官方 <cap-widget> 的框架封装,提升开发体验 React、Angular、Vue、通用组件
Hooks 基于 Cap API 的 React Hook 实现,可完全自定义用户体验 React
Server 独立实现签发与验证逻辑的服务端库 Cloudflare Workers、Java、Go、Python、.NET、PHP
Client 客户端库,用于发起验证请求 JavaScript (NodeJS)

官方文档明确给出了一个总体警告:社区库通常不支持新特性,例如 seeded challenges(基于种子的挑战,即 HashWX)或 instrumentation challenges(插桩挑战)。这两项正是 Cap 区别于传统 CAPTCHA 的核心能力:

  • HashWX 是 Cap 的默认挑战协议,每个挑战都从随机种子生成一个新的单向函数,使 GPU 相对 CPU 的加速比从 SHA-256 的约 150 倍降到约 2 倍;
  • Instrumentation 每次请求生成一段唯一 JavaScript 在浏览器内执行,服务端校验真实浏览器环境,可额外启用自动化浏览器检测。

在选用社区库时,需确认它是否跟上这两项协议,否则你将退回到经典的 SHA-256 PoW 流程。

Widgets:框架封装层

Widgets 是对官方 <cap-widget> 的包装。官方组件本身是 Web Component,任何框架都能用原生标签渲染,因此文档强调"通常不是必需的",但封装后的事件处理、类型提示和属性绑定会显著改善开发体验。

社区可用的 Widget 封装包括:

  • React
    • @pitininja/cap-react-widget
    • cap-widget:一个无头(headless)、兼容 shadcn 的 React 组件
  • Angular
    • @espressotutorialsgmbh/cap-angular-widget
  • Vue
    • nuxt-cap
  • 其他
    • better-captcha:框架无关的 Widget,支持 6 种框架,包括 React、SolidJS、Vue、Svelte 等

想理解这些封装在做什么,可以参考官方 Widget 的使用方式:原生写法只需在表单内放置 <cap-widget data-cap-api-endpoint="https://<instance>/<site-key>/">,监听 solve 事件拿 e.detail.token,或依赖自动注入的表单字段 cap-token。完整的框架示例与事件表见 Widget 文档。

Widget 还暴露了若干全局配置点,社区封装通常也会透传这些能力(详见 widget/src/src/cap.js):

  • window.CAP_CUSTOM_FETCH:自定义 fetch 函数,用于注入请求头或走代理;
  • window.CAP_CUSTOM_WASM_URL / window.CAP_CUSTOM_HASHWX_URL:自定义 WASM 资源地址;
  • window.CAP_SCRIPT_NONCE / window.CAP_CSS_NONCE:在严格 CSP 下为非阻塞的注入脚本/样式提供 nonce;
  • data-cap-worker-count:求解 Worker 数量,默认取 navigator.hardwareConcurrency || 8。

Hooks:完全自定义的 React 体验

Hooks 分类目前只有一个库:@takeshape/use-cap。它是 Cap API 的 React Hook 实现,适合需要完全掌控用户交互流程(而非渲染标准复选框)的场景——例如把验证过程嵌入自定义按钮、向导或支付流程。官方对应能力是 Programmatic 模式:new Cap({ apiEndpoint }).solve() 返回 { token },不渲染任何可见元素。

Server:各语言的服务端实现

这一分类是社区生态的绝对主体。文档给出的警告也更重:这些库由社区维护,未经 Cap 官方支持或安全审查,无法保证质量、安全性或兼容性,且可能不支持 storage hooks 或 seeded challenges 等新特性。

按语言/平台逐一列出:

Cloudflare Workers(Serverless / JavaScript)

  • kaerez/CFCap:基于 Cloudflare Workers 的无服务器实现,使用 R2 Buckets(比 Durable Objects 更便宜),支持可自定义 TTL、可选使用托管的 JS 与 WASM、全球边缘部署与自动扩缩。
  • xyTom/cap-worker:基于 Cloudflare Workers + Durable Objects 的无服务器实现,支持全球边缘部署与自动扩缩。

这两个实现都是无状态、边缘友好的路线,与 capjs-core 的定位一致——capjs-core 本身就是为 "不能跑 Docker、需要嵌入现有服务、或部署到无持久化存储环境(Workers/Lambda/边缘函数)" 而设计的,见 capjs-core 文档。实际上,用 capjs-core 直接在 Worker 上实现 /challenge 与 /redeem 两个路由即可完成等效功能,文档还给出了完整的 Worker 示例代码。

Java

  • luckygc/cap-server:替代 wuhunyu 的 Java 服务器实现,修复了一个重要问题。
  • wuhunyu/cap-server-java
  • schwebke/cap-captcha-keycloak:Keycloak 扩展,为注册流程提供 Cap 验证。

Go

  • samwafgo/cap_go_server
  • ackcoder/go-cap

Python

  • capjs-server:无状态 Python 服务器库,用于 Cap 令牌验证,无需数据库。
  • django-cap:基于 Django 的 Cap 服务端实现。

.NET

  • izanhzh/pow-cap-server

PHP

  • clysss/capito:Capito Cap PHP 服务器。
  • trilbymedia/cap-php:Cap proof-of-work 验证服务器的 PHP 移植。
  • oliweb-proof-of-work-for-cap:WordPress 插件,将 Cap 集成到评论、登录、注册与 WooCommerce 结账流程,同时支持可见 Widget 与隐形(programmatic)模式。
  • laravel-cap:Laravel 集成——Blade 指令、中间件、验证规则与服务门面(facade),用于服务端令牌验证(composer require oliweb/laravel-cap)。
  • statamic-cap:Statamic 插件,将 Cap 集成到表单——Widget 渲染、自动令牌验证与灵活的 CP 配置(composer require oliweb/statamic-cap)。
  • cap-captcha-wordpress:WordPress 插件,将 Cap 集成到认证流程与评论,可在 WordPress 管理后台配置实例、密钥与颜色。

Client:客户端验证库

  • cap-client(codeberg 上的 sanin/cap-client):客户端库 + Express 中间件,用于发起验证请求,面向 NodeJS。

如果你只需要在 NodeJS 后端验证令牌,capjs-core 本身已提供 validateChallenge(无状态、JWT 校验),社区 client 库可视为另一种选择。

不依赖社区库:官方验证路径

社区库并非必需。Cap 官方为每种场景都提供了不依赖第三方代码的接入方式,这也是文档标题点明的主题——"在没有官方 SDK 的情况下验证 proof-of-work 令牌"。

路径一:Standalone 的 siteverify(任何语言都适用)

如果你的后端是任何能用 HTTP POST 的语言,直接用 Standalone 安装指南 部署服务端,然后调用 /siteverify 即可,与语言无关:

curl "https://<your-instance>/<site-key>/siteverify" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "secret": "<key_secret>", "response": "<captcha_token>" }'

成功返回 { "success": true }。其中 <key_secret> 是站点密钥的 secret key(不是仪表盘 ADMIN_KEY),<captcha_token> 是 Widget 生成的令牌(表单字段 cap-token 或 solve 事件的 e.detail.token)。完整的多语言示例(curl / fetch / Python / PHP)见 快速开始。

从源码看,siteverify 的实现要点如下(standalone/src/siteverify.js):

  • 令牌格式为 sitekey:id:secret 三段式,缺段返回 400;
  • response 前缀必须匹配路径中的 siteKey;
  • 用 GETDEL 原子取删存储中的令牌——令牌是单次使用的,重放会返回 404;
  • 过期时间小于当前时间返回 403。

这套接口与 reCAPTCHA 的 siteverify 兼容,迁移 reCAPTCHA 代码时只需更换 URL。

路径二:capjs-core(无状态、可嵌入现有服务)

当你想把挑战签发直接嵌入现有服务(Worker、Lambda、边缘函数),或不想引入数据库时,使用 capjs-core:

import { generateChallenge, validateChallenge } from "capjs-core";

const SECRET = process.env.CAP_SECRET; // ≥16 字节,跨进程保持一致

// 1) 签发挑战
const ch = await generateChallenge(SECRET, {
  scope: "signup",
  instrumentation: true,
});
// → { challenge: { c, s, d }, token, expires, instrumentation? }

// 2) 验证解并赎回
const result = await validateChallenge(SECRET, {
  token: req.body.token,
  solutions: req.body.solutions,
  instr: req.body.instr,
}, {
  scope: "signup",
  consumeNonce: async (sigHex, ttlMs) =>
    myStore.setIfNotExists(`cap:${sigHex}`, 1, ttlMs),
});

generateChallenge 返回 JWT 签名的挑战令牌(HMAC 细节见 core/src/crypto.js 的 jwtSign / jwtVerify),validateChallenge 校验 PoW 解与(可选的)插桩结果。由于库本身无状态,重放防护必须由你通过 consumeNonce 回调实现,文档给出了 Redis(SET NX EX)、Cloudflare KV、PostgreSQL 唯一约束三种参考实现。

路径三:自实现令牌消费

如果你在自己的后端签发了令牌(例如基于 capjs-core 或自定义协议),文档也给出了不依赖官方 SDK 的校验思路:把用户提交的令牌拆成 id 与 verToken 两部分,用 SHA-256 对后者取哈希得到 tokenKey,再查存储中的过期时间:

import { createHash } from "node:crypto";

const [id, verToken] = req.body.token.split(":");
const tokenKey = `${id}:${createHash("sha256").update(verToken).digest("hex")}`;
const expires = await myStore.get(`cap-token:${tokenKey}`);
if (!expires || Number(expires) < Date.now()) {
  return res.status(401).end();
}

Standalone 的 signToken 生成 sitekey:redeemId:redeemSecret 三段令牌(standalone/src/cap.js),与 siteverify 的解析逻辑一致,可作为参考。

社区库 vs 官方路径:怎么选

结合原文档的警告与官方能力,可以给出如下选择矩阵:

你的场景 建议路线
能跑 Docker,想要仪表盘、多站点密钥、统计与限流 官方 Cap Standalone + 任意语言的 HTTP 调用
Cloudflare Workers / Lambda / 边缘函数,无持久化存储 官方 capjs-core(自带 Worker 示例),或社区 CFCap / cap-worker
Java / Go / .NET / PHP 服务端 对应语言的社区 Server 库,或自行实现签发/验证协议
框架内想要更好的 Widget 开发体验 官方 Widget 本身即可,按需选社区 Widget 封装
需要 HashWX / instrumentation 等新能力 优先官方 Standalone 或 capjs-core——社区库可能不支持

贡献与生态扩展

原文档将社区库定位为持续生长的生态:如果你实现了新的语言绑定或框架封装,可以提交 Pull Request 把它补充到文档中。新库提交时,建议在描述中说明其支持的特性范围——特别是是否支持 seeded challenges(HashWX)与 instrumentation challenges,方便使用者快速判断是否满足自己的防护需求。参考 CONTRIBUTING.md 了解项目贡献约定。

结语

Cap 的社区生态本质上是"协议层"的多种实现:官方 Widget 与 Standalone 定义了标准交互协议,社区库则在不同语言和平台上重写服务端。理解这条链路的关键在于两点——令牌验证协议本身足够简单(签发挑战、校验解、一次性消费),以及新特性(HashWX、instrumentation)常常滞后于社区库。因此,安全敏感的生产环境建议优先使用官方 Standalone 或 capjs-core;社区库更适合快速接入原型、语言强约束或资源受限的边缘部署场景。无论哪条路线,你都可以随时回到 社区库文档 找到对应的现成实现。

登录后查看全文
cap