网络安全应用安全后端【免费下载链接】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 的 Checkpoint此前称为 middleware是一套开箱即用的服务端中间件用于复刻 Cloudflare 的浏览器检查过渡页browser check interstitial在请求到达你的真实业务路由之前先要求浏览器完成一次自托管、开源的工作量证明proof-of-workCAPTCHA从而把 bot、LLM 与自动化滥用挡在网站之外。本文以仓库中 docs/th/guide/middleware/index.md其英文原版见 docs/guide/middleware/index.md为核心骨架结合 Cap Standalone 服务端源码讲解 Checkpoint 的工作机制并给出 Express、Hono、Elysia 三个框架的完整接入代码与全部配置参数帮助你在一行行代码中落地自己的核弹级反机器人防线。什么是 Cap CheckpointCheckpoint 是 Cap 生态中与 独立服务端Cap Standalone 配合使用的一组中间件包。它解决的核心问题是在 bot、LLM 爬取和自动化滥用真正触达你的业务接口之前先拦截它们。其效果等价于把整个网站搬到 Cloudflare 之后由 Cloudflare 免费附带的浏览器质询但实现方式完全不同——你不需要迁移任何基础设施只需在自己的服务器上引入几行代码。与直接把整个网站托管给 Cloudflare 相比Checkpoint 的优势非常直观改动极小不涉及 DNS、CDN 或全站迁移只在应用服务中加入一个中间件完全自托管挑战的生成、验证、token 存储全部运行在你的服务器或你自己的 Cap Standalone 实例上数据与策略都掌握在自己手中开源透明挑战算法与验证逻辑来自仓库中的 standalone/src/cap.js 等可审计代码。不过官方文档也给出了一条非常重要的提醒这是一种核弹级nuclear方案——因为它面向的是真实浏览器 人类用户这一假设搜索引擎爬虫、价格监控脚本、各类合法自动化工具同样会被挡在门外。如果你的站点依赖搜索引擎自然流量部署前必须评估其对 SEO 的冲击。Checkpoint 的工作链路要正确使用 Checkpoint先理解它站在 Cap 服务端能力之上的完整请求链路会很有帮助。从 standalone/src/cap.js 的源码结构看一次完整的 Checkpoint 交互大致分为四个阶段Challenge 签发浏览器或隐藏的 solver向 Cap Standalone 的 challenge 接口请求一个待求解的工作量证明挑战。源码在签发时按 site key 的协议配置选择三种算法之一standalone/src/cap.jssha256-pow经典 SHA-256 工作量证明可用challengeCount默认 80、saltSize默认 32、difficulty默认 4调节强度rsw基于 RSW 时间锁谜题通过rswT默认 75_000 ms允许 10_000–300_000 ms 区间控制耗时hashwx哈希工作量证明通过hashwxDifficulty默认 1_000_000允许 50_000–5_000_000 区间控制难度。每次签发的挑战都带有expiresMs: CHALLENGE_TTL_MS源码中定义挑战有效期CHALLENGE_TTL_MS 15 * 60 * 100015 分钟standalone/src/cap.js并写入scope: params.siteKey以绑定站点。浏览器求解Checkpoint 中间件的过渡页模板中必须包含 Cap 的 widget 或隐藏 solver且指向/__cap_clearance这个 URLElysia 版文档的 NOTE 对此有明确要求。求解完成后前端把token与solutions提交给服务端的 redeem 接口。Redeem 验证与 token 签发服务端调用核心库的coreValidateChallenge做密码学校验standalone/src/cap.js包括consumeNonce用SET ... NX EX把已用过的签名写入blocklist:键防止重放攻击signToken生成siteKey:redeemId:redeemSecret三段式票据校验通过后把票据以token:前缀写入存储并设置EX过期standalone/src/cap.js服务端定义TOKEN_TTL_MS 2 * 60 * 60 * 10002 小时standalone/src/cap.js。这一阶段还会处理多种失败原因expired挑战过期、scope_mismatch挑战 token 与 site key 不匹配、already_redeemed重复兑换、以及 instrumentation 相关的一族错误instr_corrupted、instr_expired、instr_automated_browser、instr_timeout、instr_missing见 standalone/src/cap.js——后者正是 Cap 的instrumentation 挑战能力通过检测自动化浏览器行为大幅抬高 bot 门槛。Siteverify 放行用户完成挑战并拿到合法 token 后你的业务后端在信任其请求之前向 Cap Standalone 的/siteverify端点做一次服务端验证standalone/src/siteverify.js。验证逻辑包含校验secret与 site key 的对应关系verifySecret并自动把旧版密码 KDF 哈希升级为 SHA-256、校验 token 三段式格式、用GETDEL一次性消费 token防止同一 token 被重复使用、检查过期时间standalone/src/siteverify.js。验证成功返回{ success: true }。Checkpoint 中间件正是把第 2 阶段的过渡页和放行逻辑封装成了对业务代码几乎零侵入的插件。接入前置条件在向 Express / Hono / Elysia 添加 Checkpoint 之前请确认以下两件事就绪Cap Standalone 后端可访问Checkpoint 需要依赖 Cap 的 challenge / redeem / siteverify 能力因此先按 standalone 部署指南 用 Docker 起一个实例docker compose up -d在管理面板创建 site key记录 site key 与 secret key。注意实例必须能被公网访问widget 才能与它通信。准备过渡页模板Checkpoint 的verification_template_path指向一个 HTML 模板文件。官方文档强调模板只需要包含一个指向/__cap_clearanceURL 的 widget 或隐藏 solver即可其余页面样式完全由你决定。也就是说你可以把这个过渡页做成与站点一致的白标页面。在 Express 中接入 CheckpointExpress 版使用官方包cap.js/checkpoint-express配套cookie-parser管理放行 cookie。安装命令docs/th/guide/middleware/express.mdbun add express cookie-parser cap.js/checkpoint-express接入示例import express from express; import cookieParser from cookie-parser; import path from path; import { dirname } from path; import { fileURLToPath } from url; import { capCheckpoint } from cap.js/checkpoint-express; const app express(); const __dirname dirname(fileURLToPath(import.meta.url)); app.use(express.json()); app.use(cookieParser()); app.use( capCheckpoint({ /* token_validity_hours: 32, tokens_store_path: .data/tokensList.json, token_size: 16, verification_template_path: join(__dirname, ./index.html), */ }), ); app.get(/, (req, res) { res.sendFile(path.join(__dirname, success.html)); }); app.listen(3000, () { console.log(Server running on http://localhost:3000); });要点说明app.use(capCheckpoint({ ... }))注册在业务路由之前因此所有后续路由都默认受到保护如果你只想保护部分接口可以把它挂在特定路径前缀上注释块中的四个参数为可选配置取消注释即启用自定义值默认值见下文参数表通过校验的浏览器拿到放行 cookie之后请求可直接通过无需反复解题根路由返回success.html即用户完成检查后进入的真实页面。在 Hono 中接入 CheckpointHono 版使用cap.js/checkpoint-hono用app.use(*, capCheckpoint(...))全局挂载适合 Bun 上的轻量 Hono 应用docs/th/guide/middleware/hono.mdbun add hono cap.js/checkpoint-honoimport { Hono } from hono; import { serveStatic } from hono/bun; import { capCheckpoint } from cap.js/checkpoint-hono; const app new Hono(); app.use( *, capCheckpoint({ token_validity_hours: 32, // token 有效时长小时 tokens_store_path: .data/tokensList.json, token_size: 16, // token 大小字节 verification_template_path: join(dirname(fileURLToPath(import.meta.url)), ./index.html), }), ); app.get(/, (c) c.text(Hello Hono!)); export default app;这段示例把四个可选参数全部显式配置出来token_validity_hours决定签发 token 的有效时长tokens_store_path指定已签发 token 的持久化文件位置token_size指定 token 的字节长度verification_template_path指向你的过渡页模板。在 Elysia 中接入 CheckpointElysia 版使用cap.js/middleware-elysia示例还额外展示了scoping参数docs/th/guide/middleware/elysia.mdbun add elysia cap.js/middleware-elysiaimport { Elysia, file } from elysia; import { capMiddleware } from cap.js/middleware-elysia; new Elysia() .use( capMiddleware({ token_validity_hours: 32, // token 有效时长小时 tokens_store_path: .data/tokensList.json, token_size: 16, // token 大小字节 verification_template_path: join(dirname(fileURLToPath(import.meta.url)), ./index.html), scoping: scoped, // global | scoped }), ) .get(/, () Hello Elysia!) .listen(3000);[!NOTE] 过渡页模板只需要包含一个指向/__cap_clearanceURL 的 widget 或隐藏 solver 即可正常工作你可以在该模板中自由设计页面外观。scoping允许scoped或global作用域控制 token 是限定在单个站点上下文还是全局有效。这一概念与 Cap 服务端的管理面设计相呼应——例如 standalone/src/server.js 中的scopeGuard会把 API key 的权限限定到特定 site key只读 key 还会拒绝非 GET/HEAD 请求同理scoped 的挑战 token 也会在 redeem 阶段被scope_mismatch校验拦下standalone/src/cap.js确保一个站点签发的 token 无法被用于另一个站点。Checkpoint 配置参数速查综合三个框架的官方示例Checkpoint 中间件的配置参数如下参数示例值含义token_validity_hours32放行 token 的有效时长小时到期后浏览器需重新完成检查tokens_store_path.data/tokensList.json已签发 token 的持久化存储文件路径用于服务重启后仍可校验token_size16生成 token 的字节大小影响 token 的随机强度verification_template_pathjoin(__dirname, ./index.html)浏览器检查过渡页模板的绝对/相对路径模板须包含指向/__cap_clearance的 widget 或隐藏 solverscoping仅 Elysia 版scopedtoken 作用域可选global或scoped需要说明的是中间件层面签发的放行 token 生命周期由token_validity_hours控制而 Cap Standalone 服务端对 challenge 与 redeem 票据分别内置了 15 分钟挑战有效期与 2 小时 token 有效期见 standalone/src/cap.js两层生命周期相互独立、共同构成防线。部署注意事项对善意的 bot 同样生效Checkpoint 无法区分坏 bot和好 bot搜索引擎爬虫、RSS 抓取器、CI 健康检查等无头请求都会被要求解题。官方文档用核弹级来描述这一点请结合业务对 SEO 和可访问性的要求决定是否全局启用。验证模板必须自持每个框架的过渡页模板都要自带指向/__cap_clearance的 widget 或隐藏 solver否则检查流程无法完成。前后端都要校验中间件只负责前端放行真正决定是否信任的是服务端对 token 的siteverify校验一次性消费 过期检查standalone/src/siteverify.js。生产环境应在业务后端显式调用/siteverify而不是只依赖 cookie。逆代与限流如果你的实例在反向代理之后请参照 standalone 配置指南 正确配置 IP 头与限流源码中默认依次读取X-Forwarded-For、X-Real-IP、CF-Connecting-IP见 standalone/src/cap.js。至此你已经在三个主流框架中完成了 Cap Checkpoint 的接入。相比把整个站点交给 Cloudflare这套方案把浏览器检查这一能力重新放回你自己的服务器与代码中几行中间件代码、一个自托管后端以及一份完全可控的 proof-of-work 防线。赞分享网络安全应用安全后端【免费下载链接】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点击查看免费下载相关推荐Solving Cap Proof-of-Work Challenges Server-Side with cap.js/solver on BunSolving Cap Proof of Work Challenges Server Side with cap.js/solver on Bun 本指南讲网络安全应用安全后端Encore 数据库 Schema 迁移实战用 Migration Files 安全演进 SQL 数据库结构Encore 数据库 Schema 迁移实战用 Migration Files 安全演进 SQL 数据库结构 导读 本文围绕 Encore 平台内置的数据库网络安全应用安全后端Cap 与 Cloudflare Turnstile 深度对比从托管式指纹 CAPTCHA 到自托管 Proof-of-Work 的迁移实践Cap 与 Cloudflare Turnstile 深度对比从托管式指纹 CAPTCHA 到自托管 Proof of Work 的迁移实践 本篇技术指南以仓网络安全应用安全后端上一篇3 步 2 条红线CodeWhale simplify 技能安全瘦身代码实战指南下一篇JavaScript事件循环终极指南深入理解异步编程运行机制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考