Cap 社区生态指南:多语言/多框架库与不依赖官方 SDK 的令牌验证
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 由两部分组成:
- 客户端 Widget:一个原生 Web Component(
<cap-widget>),负责向后端请求挑战、在浏览器内用 WASM 求解 proof-of-work,并在通过后拿到令牌。它不依赖任何框架,可在任何现代浏览器中直接使用。 - 服务端:推荐 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-widgetcap-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-javaschwebke/cap-captcha-keycloak:Keycloak 扩展,为注册流程提供 Cap 验证。
Go
samwafgo/cap_go_serverackcoder/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;社区库更适合快速接入原型、语言强约束或资源受限的边缘部署场景。无论哪条路线,你都可以随时回到 社区库文档 找到对应的现成实现。