网络安全应用安全后端【免费下载链接】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 Standalone 是 cap 项目自托管模式的核心后端它暴露了一套基于 Bearer / Bot 认证的 REST API用于创建、查看和管理 CAPTCHA 的 site key 与 session以及生成面向第三方的公开统计分享链接。读完本文你将掌握如何从仪表盘或纯 API 创建 API key、如何理解Bot认证头与权限模型只读、按 site key 限定、如何使用/share/:token系列端点安全地对外分享只读统计以及 Swagger 文档与各类端点的参数边界。一、API 概览与获取 API KeyStandalone 模式代码位于 standalone/src/server.js提供一套小而简单的 REST API创建、查看和管理 key 与 session。所有管理类端点挂在/server前缀下并且要求携带 API key 或会话 tokenSwagger 中统一标记为apiKey安全方案见 standalone/src/index.js。获取 API key 的完整流程打开你的 Cap Standalone 仪表盘http://localhost:3000用ADMIN_KEY登录进入Settings → API Keys给 key 起一个名字点击 Create立刻妥善保存返回的 key—— 系统只展示这一次之后无法再次查看明文。从源码看key 的生成在 standalone/src/server.jsid是 16 字节随机数hex 编码token是 32 字节随机数base64url 编码二者拼接为${id}_${token}返回给调用方数据库里只保存tokenHash经Bun.password.hash哈希因此服务端自身也无法还原明文 token这正是只能看一次的原因。二、认证方式Bot前缀与 Session Token每次 API 请求都必须携带Authorization请求头格式如下Authorization: Bot YOUR_API_KEY服务端解析逻辑在 standalone/src/auth.js 中请求头以Bot开头时把剩余部分按下划线拆成id和token两段从 Redis 读取apikey:{id}记录并取回tokenHash、siteKeys、readonly三个字段再用Bun.password.verify校验 token。任何一段缺失、id 不存在或校验失败都会返回401与对应的错误消息例如Deleted or non-existent bot token。此外还有第二种认证方式登录POST /auth/login见 standalone/src/auth.js返回的session_token与hashed_token会拼成 JSON 并 base64 编码后放入Authorization: Bearer ...。/server下的管理端点同时接受这两种凭据。三、Swagger交互式端点清单所有可用端点及其请求体body定义都可以在 Swagger 界面查看http://localhost:3000/swaggerSwagger 由 standalone/src/index.js 中的elysiajs/swagger插件提供端点按标签分组标签覆盖范围认证要求Keyssite key 的增删改查、统计、分享链接、IP 封禁需要 API key 或 session tokenSettingssession、API key、请求头、限流、CORS、过滤、IP 数据库、RSW需要 API key 或 session tokenShare通过分享 token 读取只读统计无需认证仅限流Health存活与就绪检查无需认证Challenges/Assets挑战与静态资源无/server路由定义在 standalone/src/server.js全部端点先经过authBeforeHandle认证再经过scopeGuard权限裁剪与demoWriteGuard演示模式写保护这三道前置钩子共同构成 API 的安全边界。四、Scoped API Keys按 site key 限定 只读默认情况下一个 API key 可以读写实例上的每一个site key。在Settings → API Keys创建 key 时可以收窄权限Site key access按 site key 限定勾选具体的 site key 后该 key 只能调用这些 key 的/server/keys/:siteKey/...端点GET /server/keys只列出被授权的 key访问任何其他端点包括所有 settings 端点一律返回403。Read-only只读只允许GET以及HEAD请求。任何创建、更新、轮换或删除操作都返回403。两种限制可以叠加。例如把只读 限定到单个 site key的 key 交给该网站的所有者对方就能拉取自己的统计并接入自己的仪表盘而无法窥探或改动任何配置。同样的选项也可以通过 API 创建 keyPOST /server/settings/apikeys Content-Type: application/json { name: acme stats, siteKeys: [site key], readonly: true }源码细节standalone/src/server.jssiteKeys数组会先逐个校验是否存在不存在的 key 返回400 Unknown site key创建时id16 字节 hex与token32 字节 base64url拼接成apiKey: {id}_{token}作为响应readonly: true与siteKeys会以字段形式写入 Redis hash权限裁决逻辑在scopeGuardstandalone/src/server.js只读 key 遇到非 GET/HEAD 方法直接403带 site key 限定范围的 key 只能访问路径参数命中其授权列表的端点GET /server/keys则被放行但结果会被过滤。权限行为在 standalone/test/scoped-keys.test.js 中有完整测试覆盖只读限定 key 读取 A 成功、读取 B 返回403、轮换 secret 返回403且错误信息匹配/read-only/限定可写 key 可以给自己的 key 创建 share 链接但给其他 key 创建或新造 site key 一律403只读未限定 key 可以读取 settings 但不能写入任何带 site key 限定的 key 都无法创建新的 API key防止权限升级历史上在该选项存在之前创建的 key 不受影响保持完整权限对应测试unscoped key keeps full access。五、Share Links公开的只读统计页Share link 是针对单个 site key的公开只读统计页。在仪表盘中打开某个 key进入Configuration → Share links即可创建。任何拿到链接的人都能看到该 key 的 challenge 与验证计数、活动图表以及位置国家/ASN、网络、平台和操作系统的分布他们看不到key 的配置、secret 或封禁规则也无法修改任何东西链接可以设置标签label与过期日期也可以随时在同一区块撤销revoke。5.1 隐私设计token 藏在 URL fragment链接的 token 放在 URL 的 fragment#之后中因此页面请求本身不会携带 token不会经 referer 请求头泄露但页面发出的两条 API 调用会把 token 放进路径里所以记录请求路径的反向代理仍然会看到 token—— 部署时需要注意日志脱敏。5.2 两个无认证、限流的数据端点不想用页面、想直接把数字嵌到别处时可以使用 token 访问两个无需认证、带速率限制的端点GET /share/:token?chartDurationlast7days GET /share/:token/geo-statschartDuration可选值与 standalone/src/stats.js 中chartDurations常量完全一致取值含义today今天按小时分桶yesterday昨天按小时分桶last7days最近 7 天按天分桶last28days最近 28 天按天分桶last91days最近 91 天按天分桶alltime全部历史按天分桶端点实现在 standalone/src/share.jstoken 必须匹配/^[A-Za-z0-9_-]{32}$/32 字符 base64urlcreateShare用randomBytes(24).toString(base64url)生成测试 standalone/test/scoped-keys.test.js 也断言了token长度为 32校验采用哈希后timingSafeEqual比较避免时序侧信道token 无效、过期或对应 site key 已被删除统一返回404 Share link not found or expired两个端点共享限流配置每 10 秒最多 30 次请求valkeyRateLimit({ duration: 10_000, max: 30 })统计结果带 10 秒内存缓存上限 500 条见 standalone/src/share.js所以高频轮询不会压到 Redis响应中siteKey、config、key等内部字段会被剥离publicShare与测试断言page.json.siteKey/page.json.config为undefined未命名链接默认显示Shared stats而非泄露 site key 名称。5.3 通过 API 创建与撤销POST /server/keys/:siteKey/shares请求体参数name可选链接标签最大 64 字符expiresIn以秒为单位的过期时间取值范围0–315360000。省略或传0表示永不过期对应 standalone/src/share.js 中expires expiresIn ? created expiresIn * 1000 : 00即永久且不会写入 Redis TTL。创建成功后返回id、token、name、created、expires永不过期为null。撤销则调用DELETE /server/keys/:siteKey/shares/:idrevokeSharestandalone/src/share.js会先校验该 share 归属当前 site key从其他 key 名下撤销会返回404测试a failed revoke leaves the link working验证了失败撤销不影响原链接删除 site key 时其所有 share 链接也会被一并清理deleteSharesForKey对应测试deleting the key removes its share links。六、管理端点全景Keys / Settings除 API key 与 share 之外/server还提供完整的 key 生命周期管理与实例级设置全部受 scope 规则约束Keys 端点standalone/src/server.js方法与路径说明GET /server/keys列出 site key附带 24 小时解题数与环比变化solvesLast24h、differencePOST /server/keys创建 site key返回siteKey与secretKeysk-前缀仅返回一次GET /server/keys/:siteKey查看单个 key 配置与指定chartDuration的统计PUT /server/keys/:siteKey/config更新 key 配置见下方参数表DELETE /server/keys/:siteKey删除 key 及其全部指标与封禁数据POST /server/keys/:siteKey/rotate-secret轮换 secret key返回新secretKeyGET /server/keys/:siteKey/geo-stats国家 / ASN / 平台 / 操作系统分布GET/POST /server/keys/:siteKey/shares、DELETE /server/keys/:siteKey/shares/:id管理 share 链接POST /server/keys/:siteKey/block-ip、POST /server/keys/:siteKey/unblock-ip、GET /server/keys/:siteKey/blocked-ips按 IP / CIDR / ASN / 国家封禁与解封duration为秒0为永久创建 key 时除name外还支持instrumentation、blockAutomatedBrowsers、corsOrigins、rsw、rswT、protocolsha256-pow/rsw/hashwx、hashwxDifficulty等可选字段standalone/src/server.js未显式指定时使用keyDefaults默认值difficulty: 4、challengeCount: 80、obfuscationLevel: 3、protocol: hashwx、hashwxDifficulty: 1_000_000等standalone/src/server.js。更新配置时的参数校验边界参见 standalone/src/server.jsdifficulty1–8、challengeCount1–500、obfuscationLevel1–10、rswT10000–300000、hashwxDifficulty50000–5000000 等。Settings 端点standalone/src/server.jsGET/POST /server/settings/apikeys管理与创建 API key、GET/DELETE /server/settings/apikeys/:id、GET /server/settings/sessions列出会话token 只显示末 14 位、GET/PUT /server/settings/headersipHeader/countryHeader/asnHeader、GET/PUT /server/settings/ratelimit默认{ max: 30, duration: 5000 }、GET/PUT /server/settings/cors、GET/PUT /server/settings/filtering、GET /server/settings/ipdb、POST /server/settings/ipdb/download支持dbip/maxmind/ipinfo三种数据源以及GET /server/settings/rsw、POST /server/settings/rsw/ensure、POST /server/logout。这些端点的语义与限流、CORS、健康检查等配套配置可进一步参考 Standalone 配置选项文档。七、安全实践要点综合认证实现standalone/src/auth.js与权限测试standalone/test/scoped-keys.test.js生产环境建议最小权限为每个集成方单独创建 API key优先使用readonly: true 指定siteKeys的组合避免一个 key 拥有实例级全量写权限保密第一API key 与服务端 secret 一样只在创建时返回一次务必存入密钥管理设施数据库只存哈希任何找回明文 key的需求都应通过重新创建解决日志脱敏share token 出现在 API 路径中反向代理与访问日志需对/share/路径做脱敏处理同时不要信任X-Forwarded-For等来自客户端的头详见 配置选项文档中的限流章节实例不应直接暴露在公网善用 Swaggerhttp://localhost:3000/swagger是端点与请求体的权威来源对接前先在此核对字段类型与取值范围减少联调返工。Cap Standalone 的这套 API 把站点接入与运营管理解耦得相当清晰对外只读的 share 端点让数据共享不再需要暴露管理凭据对内scoped read-only 的 Bot key 让多团队协作时的权限边界有据可依。配合 Standalone 使用指南 中的 Docker 部署与 widget 接入方式即可完整跑通自托管 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点击查看免费下载相关推荐Cap Standalone 管理 API 完全指南API 密钥、作用域授权与共享统计链接Cap Standalone 管理 API 完全指南API 密钥、作用域授权与共享统计链接 Cap 的 Standalone 模式为自托管 CAPTCHA 服网络安全应用安全后端使用 aws apigateway update-api-key 管理 API Key从 PATCH 操作到实战示例使用 aws apigateway update api key 管理 API Key从 PATCH 操作到实战示例 导读 本文以 awscli/exampl开发工具云原生运维Sink REST API 完整实战指南用 OpenAPI 在 Cloudflare 上管理短链接与统计Sink REST API 完整实战指南用 OpenAPI 在 Cloudflare 上管理短链接与统计 Sink 是一款完全运行在 Cloudflare 上后端前端数据分析云原生上一篇Unity协程完整指南从Coroutine类到迭代器模式的终极解析下一篇Semaphore内存泄漏排查Go语言性能分析工具应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考