网络安全应用安全后端【免费下载链接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.项目地址https://gitcode.com/gh_mirrors/cap13/cap点击查看免费下载本篇技术指南围绕 Cap 项目中的capjs-core无状态服务端库展开。它负责生成并校验基于 JWT 的 proof-of-work 挑战是 Cap Standalone 内部使用的同一套引擎也可被直接嵌入任何现有服务或部署到 Cloudflare Workers、Lambda、边缘函数等无持久存储的环境。读完本文你将掌握capjs-core的安装方式、generateChallenge/validateChallenge两个核心 API 的全部参数与失败语义、基于consumeNonce的重放防护、instrumentation 浏览器检测层以及 HashWX 多协议挑战格式format 2的无状态部署模式。什么时候直接使用 capjs-core而不是 Cap StandaloneCap 提供了一条「开箱即用」的主路径Cap Standalone 基于 Docker 运行、附带仪表盘与全套配置适合大多数用户。而capjs-core是 Cap 的无状态服务端库其定位恰恰是那些 Standalone 覆盖不到的场景参见 docs/guide/capjs-core.md无法运行 Docker 的环境想把挑战生成嵌入到已有服务内部而不是独立部署一个服务需要部署到无持久存储的运行时Cloudflare Workers、Lambda、边缘函数。核心库的设计哲学是「无状态、自带存储」挑战令牌本身是携带配置与过期时间的签名 JWT不需要服务端保存任何会话状态令牌的消费防重放与兑换令牌的存储则由调用方通过回调自行决定。安装capjs-core是发布在 npm 生态上的独立包当前仓库中的版本为 0.1.3见 core/package.json包入口为src/index.jsESM 模块随包附带完整 TypeScript 类型声明src/index.d.ts。三种主流包管理器均可安装bun add capjs-corenpm i capjs-corepnpm i capjs-core依赖方面esbuild是必需依赖用于 instrumentation 脚本的压缩javascript-obfuscator是可选依赖仅在使用高混淆等级时按需加载见 core/package.json。快速上手生成与校验挑战库的核心用法只有两个异步函数。下面是最小可运行的服务端流程与 core/README.md 中的示例一致import { generateChallenge, validateChallenge } from capjs-core; // 长、随机、高熵的密钥。必须在所有进程间保持一致。 const SECRET process.env.CAP_SECRET; // 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), }, ); if (result.success) { // result.token, result.tokenKey, result.expires, result.scope }整体交互流程是widget客户端组件调用你的/challenge路由拿到{ challenge, token, expires, instrumentation }在浏览器端求解 proof of work然后把{ token, solutions, instr }POST 回你的/redeem路由服务端调用validateChallenge完成校验。token一旦签发即可在 10 分钟内任意次请求新挑战但每次校验成功只会返回一次可兑换的token配合consumeNonce可保证一次提交只能被兑换一次。与 cap.js/server 的差异方面cap.js/servercapjs-core状态内存 文件系统令牌存储无状态。挑战令牌是签名 JWT构造方式new Cap({ ... })无构造器——每次调用直接传secret防重放内建令牌列表 清理定时任务通过consumeNonce回调可选启用清理钩子SIGINT/beforeExit时冲刷无——TTL 直接编码在 JWTexp中文件系统持久化必需完全不触碰Worker 兼容否依赖文件系统是与旧库不同capjs-core不会替你校验兑换令牌——它返回一个需要你自己存储的tokenKey以及一个交给用户的token。校验时你从用户提交的 token 重新推导出 key再查自己的存储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(); }从源码看默认兑换令牌的生成逻辑与此完全一致core/src/index.js 中以randomHex(8)生成 id、randomHex(15)生成验证串token 格式为${id}:${verToken}而tokenKey为${id}:${sha256Hex(verToken)}——所以你只需用 SHA-256 哈希用户回传的验证串并连同 id 去查自己的存储即可存储里绝不需要保存明文 token。API 详解generateChallenge(secret, opts?)返回Promise{ challenge, token, expires, instrumentation? }。secret— string 或 Buffer至少 16 字节。主 HMAC 密钥必须在所有进程间保持一致。源码中assertSecret会同时校验长度与类型不满足会直接抛错core/src/index.js。opts.challengeCount— PoW 谜题数量。默认50取值范围[1, 1000]。opts.challengeSize— salt 长度十六进制字符数。默认32取值范围[1, 256]。opts.challengeDifficulty— 目标前缀长度十六进制字符数。默认4取值范围[1, 16]。难度为 4 意味着客户端需要找到让 SHA-256 输出以 4 个十六进制0开头的 nonce期望计算量约为 2^16 次哈希。opts.expiresMs— 挑战 TTL。默认600_00010 分钟。源码中对应常量DEFAULT_CHALLENGE_TTL_MS 10 * 60 * 1000。opts.scope— 可选字符串绑定到挑战。校验时必须传入相同的scope否则返回scope_mismatch。典型用法是把不同表单注册、登录、评论区分为独立 scope防止跨端点复用挑战。opts.extra— 可选对象嵌入 JWT payload持有 token 的任何人都可见不要放机密。opts.instrumentation—true使用默认配置或传入对象{ blockAutomatedBrowsers, obfuscationLevel }。opts.instrumentationGenerator— 逃生舱口用于把脚本生成卸载到 worker 池适合高并发或高混淆等级场景。从源码看生成的 JWT payload 包含字段n随机 nonce、c/s/d挑战参数、exp、iat、可选的skscope、xextra。JWT 采用 HS256 签名见 core/src/crypto.js 中的jwtSignheader 固定为{alg:HS256,typ:JWT}签名比较使用timingSafeEqual。当启用 instrumentation 时其元数据id、期望值、变量表、blockAutomatedBrowsers、过期时间会被AES-256-GCM加密后放入ei字段——这样客户端看不到校验所需的期望值也就无法直接伪造通过校验的响应。expires是 JWT 的过期时间戳毫秒。instrumentation若请求是 deflatebase64 编码的客户端脚本交给 widget 执行。validateChallenge(secret, body, opts?)返回Promise{ success: true, token, tokenKey, expires, scope, iat, riskFlags } | { success: false, reason, instr_error?, blockedBy? }。riskFlags是 instrumentation 返回的非阻断性自动化信号列表目前只有native_tamper可用于在下一次挑战时提高 PoW 难度而不是直接拒绝。blockedBy仅在reason为instr_automated_browser时出现列出具体失败的检测项。bodytoken—generateChallenge返回的挑战令牌。solutions— 数字数组长度必须等于challenge.c。源码会逐项校验每个元素必须是number类型。instr— instrumentation 结果若启用。instr_blocked、instr_timeout— widget 在 instrumentation 拒绝页面时上报的标志。optsscope— 必须与原始挑战的 scope 一致。tokenTtlMs— 兑换令牌的 TTL。默认1_200_00020 分钟对应源码常量DEFAULT_TOKEN_TTL_MS 20 * 60 * 1000。consumeNonce(sigHex, ttlMs)— 通过你的存储实现防重放见下文。signToken(data)— 异步函数返回自定义的兑换令牌格式。默认返回id:secret格式。传入data为{ scope, expires, iat }。若自定义请自行确保 token 可逆推导出存储 key例如沿用默认的id:secret结构。失败原因reasonreason含义invalid_bodybody 不是对象missing_token未提供 tokenmissing_solutionssolutions 缺失或不是数组invalid_tokenJWT 签名不匹配 / 格式错误 / 参数越界scope_mismatchtoken 的 scope 与opts.scope不匹配expired挑战 JWT 已过期invalid_solutions长度不匹配或包含非数字nonce_store_errorconsumeNonce回调抛出了异常already_redeemedconsumeNonce返回了falseinvalid_solutionsolutions 不满足 PoW 要求instr_*instrumentation 校验失败带instr_error: true源码中还会出现instr_corruptedGCM 解密失败、instr_expiredinstrumentation 元数据过期、instr_missing启用了 instrumentation 但未提交结果、instr_timeout、instr_automated_browser等细粒度原因core/src/index.js。校验顺序值得注意先验签、查过期、校验 solutions 长度与类型再逐项验证 PoW 解然后验证 instrumentation最后才调用consumeNonce。PoW 的具体验证是以 token 的 FNV-1a 哈希为种子逐项派生每个子挑战的 salt 与 target再对salt solution做 SHA-256 并比较目标前缀详见 core/src/crypto.js 的powMatchesPrefix与 core/src/prng.js。重放防护consumeNonce库本身按设计是无状态的。要防止截获的提交被兑换两次传入consumeNonce回调即可。capjs-core会用JWT 的签名十六进制和剩余 TTL 调用它你在自己的 KV 中以SET NX EX语义存储该 hex重复时返回false。import { Redis } from ioredis; const redis new Redis(process.env.REDIS_URL); const consumeNonce async (sigHex, ttlMs) { const ttlSec Math.ceil(ttlMs / 1000); const ok await redis.set(cap:${sigHex}, 1, NX, EX, ttlSec); return ok OK; };const consumeNonce async (sigHex, ttlMs) { const key cap:${sigHex}; if (await env.NONCES.get(key)) return false; await env.NONCES.put(key, 1, { expirationTtl: Math.ceil(ttlMs / 1000), }); return true; };const consumeNonce async (sigHex, ttlMs) { const expiresAt new Date(Date.now() ttlMs).toISOString(); try { await dbINSERT INTO cap_nonces (sig, expires_at) VALUES (${sigHex}, ${expiresAt}); return true; } catch (e) { if (e.code 23505) return false; // unique violation throw e; } };关键设计该检查在 PoW 与 instrumentation 验证之后才执行。这意味着攻击者即使重放截获的提交并附上乱写的 solutions也不会烧掉合法用户的 nonce非法解会在更早的阶段被invalid_solution拦截。仓库测试 core/test/core.test.js 的consumeNonce (one-time use)用例验证了回调收到的是sigHex ttl第二次提交同一 token 时返回already_redeemedcore/test/integration.test.js 也在完整挑战-校验流程中覆盖了同样的语义。Instrumentation 挑战向generateChallenge传入instrumentation: true或配置对象即可在返回值中拿到 deflatebase64 编码的客户端脚本。widget 在浏览器中执行该脚本、回传指纹validateChallenge再做服务端校验const ch await generateChallenge(SECRET, { instrumentation: { blockAutomatedBrowsers: true, // 拒绝 playwright/puppeteer/selenium obfuscationLevel: 3, // 1-10, 默认 3 }, });当blockAutomatedBrowsers开启时脚本会在浏览器中执行 realm-escape 与 marker 检查并采集一组探针向量文本度量、窗口几何、navigator.webdriver、引擎标记服务端用detectAutomation评估该向量——阻断与否由服务端裁决客户端自报的结果只是「建议」因为隐身浏览器会尝试打补丁掩盖客户端检查。完整检查清单及其各自防御对象见 docs/guide/instrumentation.md。detectAutomation(vector)也被直接导出供想对自己采集的向量运行检测器的调用方使用返回{ pass, checks, blockedBy, riskFlags }。从 core/src/detect.js 可以看到七项阻断性检查probe_incomplete、geometry_quantized、webdriver_true、webdriver_stripped、gecko_contradiction、window_exceeds_screen、viewport_override、headless_token以及非阻断的native_tamper会写入riskFlags建议据此调高下次挑战的 PoW 难度而非直接拒绝。关于混淆等级文档与源码core/src/instrumentation.js一致说明默认等级 3基础变量名随机化。等级 4–7额外叠加自定义字符串表间接寻址 esbuild 压缩。等级 8–10再叠加javascript-obfuscator字符串数组、控制流平坦化、死代码注入。等级越高生成越慢8–10 级每次挑战会阻塞事件循环数十毫秒只建议用于低流量路由或通过instrumentationGenerator自备 worker 池把生成任务卸载出去javascript-obfuscator是可选依赖未安装时高等级会自动降级见 core/package.json。无状态部署模式警告下面这些脚本没有内建防重放保护务必自行加上参考上文consumeNonce示例。Cloudflare Workersimport { generateChallenge, validateChallenge } from capjs-core; const SECRET (env) env.CAP_SECRET; export default { async fetch(req, env) { const url new URL(req.url); if (url.pathname /challenge req.method POST) { const ch await generateChallenge(SECRET(env), { instrumentation: true }); return Response.json(ch); } if (url.pathname /redeem req.method POST) { const body await req.json(); const result await validateChallenge(SECRET(env), body, { consumeNonce: async (sigHex, ttlMs) { if (await env.NONCES.get(cap:${sigHex})) return false; await env.NONCES.put(cap:${sigHex}, 1, { expirationTtl: Math.ceil(ttlMs / 1000), }); return true; }, }); return Response.json(result); } return new Response(not found, { status: 404 }); }, };Workers 场景的关键点密钥来自env.CAP_SECRET绑定nonce 存储使用 Workers KV自带 TTL 过期整个处理链路不触碰文件系统完全符合capjs-core的无状态约束。Bunimport { generateChallenge, validateChallenge } from capjs-core; const SECRET process.env.CAP_SECRET; Bun.serve({ port: 3000, routes: { /challenge: { POST: () Response.json(generateChallenge(SECRET, { instrumentation: true })), }, /redeem: { POST: async (req) { const body await req.json(); return Response.json(await validateChallenge(SECRET, body)); }, }, }, });注意上面这个极简示例省略了consumeNonce在实际生产环境中请务必补上Bun 服务同样可以直接使用 Redis/Postgres/KV 任一存储方案实现防重放。HashWX 挑战format 2自capjs-corev0.1.1 与 widget v0.1.51 起两端都支持一种更丰富的线上格式单个响应中可同时携带多种挑战协议——SHA-256 PoW默认、HashWX、已废弃的 RSW 时间锁谜题以及 instrumentation。该格式在generateChallenge中通过format: 2显式开启源码中以opts.format 2路由到独立的生成/校验路径见 core/src/index.js。最小启用方式import { generateChallenge, validateChallenge } from capjs-core; const SECRET process.env.CAP_SECRET; app.post(/api/challenge, async () { return await generateChallenge(SECRET, { format: 2, protocols: [hashwx, instrumentation], hashwxDifficulty: 1_000_000, // 可选此为默认值 }); }); app.post(/api/redeem, async (req) { return await validateChallenge(SECRET, req.body, { consumeNonce }); });HashWX不需要任何密钥材料启动时也无须配置它的哈希函数由挑战本身决定challenge十六进制串 区块号派生 seed见 core/src/hashwx.js 的hashwxSeed。首次验证时需要编译内嵌的 WebAssembly 模块耗时数毫秒建议在启动时调用一次hashwxReady()把它从第一个请求中移走。参数与默认值与 core/src/hashwx.js 常量一一对应hashwxDifficulty— 客户端必须计算的总哈希期望数默认1_000_000上限1_000_000_000。hashwxChallengeCount— 独立子挑战数量默认4上限64。难度会被均分到每个子挑战。hashwxNoncesPerHash— 每个生成哈希函数覆盖的 nonce 数默认65_536上限1_048_576。为什么要拆分子挑战单个挑战的求解时间呈指数分布一个访客可能等 30 毫秒下一个却要等 3 秒。在总难度相同的前提下拆成 4 个子挑战能让 p90 缩短约四分之一、中位数变慢约三分之一——因为无论怎么拆攻击者的期望工作量始终是d次哈希但拆分显著压低了最坏等待时间。代价是每个额外子挑战会让验证增加约 20 微秒。更详细的分析见 docs/guide/hashwx.md 的客户端成本一节。相关阅读Cap Standalone — 开箱即用的 Docker 部署方案内部正是使用 capjs-core 生成与校验挑战。Instrumentation 挑战 — 浏览器环境探测层的完整检测项清单及其防御对象。HashWX — HashWX 挑战协议的成本模型与验证细节。核心实现core/src/index.js、core/src/crypto.js、core/src/detect.js、core/src/hashwx.js类型定义 core/src/index.d.ts测试覆盖见 core/test/core.test.js 与 core/test/integration.test.js。一句话总结capjs-core用签名 JWT 把「挑战状态」随身携带把「防重放」交给你的存储回调把「浏览器环境验证」留给可选的 instrumentation 层——这让完整的 CAPTCHA 能力可以在任何无状态运行时上以极少的代码量原生落地。赞分享网络安全应用安全后端【免费下载链接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.项目地址https://gitcode.com/gh_mirrors/cap13/cap点击查看免费下载相关推荐capjs-core 无状态 CAPTCHA 挑战生成与校验Cap 服务端核心库的完整 API 实战指南capjs core 无状态 CAPTCHA 挑战生成与校验Cap 服务端核心库的完整 API 实战指南 导读 capjs core 是自托管 CAPTCHA网络安全应用安全后端DeepLab_v3与其他分割模型对比U-Net、Mask R-CNN、PSPNet终极指南DeepLab_v3与其他分割模型对比U Net、Mask R CNN、PSPNet终极指南 什么是图像分割为什么选择DeepLab_v3 图像分割capjs-core 深入指南Cap 的无状态服务端挑战生成与验证库JWT 工作量证明 插桩capjs core 深入指南Cap 的无状态服务端挑战生成与验证库JWT 工作量证明 插桩 capjs core 是 Cap 项目中面向服务端的一套网络安全应用安全后端上一篇craft.js与React 18并发特性下的编辑器性能优化下一篇phpqa开发者必备Rector自动化重构与代码风格修复实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考