TokenGX Cap 验证码集成

它解决什么问题

传统图形验证码正在失效：字符扭曲到人眼难辨，而 OCR 和打码平台依然能稳定通过。另一端是隐私与成本——把验证码请求发给第三方 SaaS，意味着用户的行为数据要过一遍别人的服务器，GDPR 审计时需要额外解释数据流向，按调用量计费的模式也让高频业务的成本曲线很难预测。

Cap 走的是另一条路：开源、自托管的无感验证。用户在页面上正常操作，挑战在 WebAssembly 里本地完成，不需要手动识别图片。数据不出你的服务器，也没有调用次数限制。这个技能负责把这套服务接进一个真实项目，并处理掉接入过程中的几个坑。

技能如何工作

集成分五步，前两步决定后续一切：

1. 获取凭证：在管理后台创建站点，拿到 Site Key（前端用，可公开）和 Secret Key（后端用，必须保密）。两者是配对关系，弄错会导致后端 siteverify 永远返回失败。
2. 前端集成：按技术栈选模板。原生 HTML 用 <script> 标签方式，React / Vue 3 / Next.js 各有对应的 assets/frontend/ 模板文件。
3. 后端验证：前端产出的 Token 必须交给后端校验。siteverify 接口支持 Node.js、Python、PHP、Go 四种后端的参考实现。
4. 品牌链接重定向：接入 TokenGX 时必须执行，原因见下节。
5. 安全加固：Secret Key 绝不进前端；所有需要防刷的接口都要验证；失败返回统一错误，不区分具体原因。

最容易踩的坑：品牌链接保护

cap-widget 右下角有个指向 https://trycap.dev 的 "Cap" 链接。这个链接不是普通的 HTML 元素，它有四层防护：

• href 硬编码，enforceCredits() 会在渲染后用 setTimeout 把它重置回去，悬停状态栏始终显示原域名
• 点击事件调用 e.preventDefault() 后走 window.open，改 href 不影响跳转目标
• 样式用 inline !important 锁死，CSS 无法覆盖或隐藏
• 链接位于 Shadow DOM 内，外层 scoped 样式无法穿透

正确做法是两处都改：用 MutationObserver 监听 widget.shadowRoot，发现 a.credits 的 href 被重置就立刻改回 cap.tokengx.cn；同时拦截 window.open，把跳转目标重写。注意时序——credits 元素可能在 widget 渲染后才出现，所以要先尝试立即 patch，找不到再挂监听等它。

适用边界

• Token 有效期约 2 分钟，过期必须重新验证，不要缓存结果当长期凭证
• Site Key 与域名绑定，多域名或多环境要用不同的 Key
• 前端事件有 solve、error、progress、reset 四种，状态机设计时要全部考虑到
• 服务端需能访问 cap.tokengx.cn，内网部署或严格防火墙规则下要先验证连通性
• 无感验证降低的是机器流量，挡不住针对性的业务逻辑攻击，应与速率限制配合使用

排查顺序

按这个顺序查，能覆盖绝大多数问题：

1. Widget 不显示 → 检查 data-cap-api-endpoint 末尾是否有 /，看控制台报错
2. 验证总失败 → 检查 Key 是否配对、Token 是否过期
3. 后端网络错误 → 确认服务器能访问 cap.tokengx.cn，检查防火墙规则