已有 AK/SK 无需重签。先把下面的应用、环境、Origin、action 替换为已有凭据的真实配置;不得擅自扩大白名单。 请为“TARGET_APPLICATION”接入 ShareAPI CAPTCHA 托管服务。服务端由 ShareAPI 托管,目标应用只接入签名 API 与前端 Widget。 接入信息: - 环境:test - 允许的 Origin:http://localhost:3100 - 允许的 action:signup, login, send_sms - CAPTCHA Base URL:https://captcha.shareapi.ai - Access Key:CAPTCHA_ACCESS_KEY_FROM_BACKEND_ENV - Secret Key:由我通过安全渠道提供;只写入业务后端环境变量 CAPTCHA_SECRET_KEY,禁止进入前端、Git、构建产物、日志或回复。 接入契约版本:customer-business-gate-v1(2026-09-05)。已有 AK/SK 继续有效,无需重新签发。 先阅读 https://captcha.shareapi.ai/docs#business-state 和 https://captcha.shareapi.ai/docs#reference。 可直接获取并审查服务方提供的客户后端参考: - https://captcha.shareapi.ai/integration/customer-gate.mjs(Node.js + PostgreSQL,签名、关联持久化、原子抢占、终验、业务事务与幂等回执) - https://captcha.shareapi.ai/integration/customer-schema.sql(迁移到目标应用自己的现有数据库) - https://captcha.shareapi.ai/integration/customer-demo.mjs 与 https://captcha.shareapi.ai/integration/customer-demo.html(localhost 验收应用,只写短信任务、不发送真实短信) 其他技术栈须实现同等状态与事务语义。不要把参考中的 localhost 演示会话当作生产身份系统。 必须完成以下闭环: 1. 在业务后端实现 ShareAPI 请求签名。每次请求生成 Unix 秒 timestamp 和至少 16 字符随机 nonce;rawBody 是实际发送的 JSON 字符串。计算: bodyHash = Base64URL(SHA256(UTF8(rawBody))) signingKey = Base64URL(SHA256(UTF8(CAPTCHA_SECRET_KEY))) canonical = "SHAREAPI-CAPTCHA-HMAC-SHA256\nPOST\n\n\n\n" signature = Base64URL(HMAC-SHA256(UTF8(signingKey), UTF8(canonical))) 请求头必须包含 X-Captcha-AK、X-Captcha-Timestamp、X-Captcha-Nonce、X-Captcha-Signature 和 Content-Type: application/json。 2. 新增业务后端接口用于申请一次性操作 Token。后端签名调用 POST https://captcha.shareapi.ai/api/v1/tokens/issue,正文为: {"action":"signup","origin":"http://localhost:3100","request_id":"每次业务操作唯一且可追踪的 UUID"} action 由真实业务路由确定;Origin 从服务端允许列表选取并验证实际请求来源;request_id 由后端生成一次,终验复用,不能重新生成或信任前端提供的值。 返回前必须先在目标应用现有数据库或持久化共享存储中提交关联:token_hash → request_id / action / origin / subject_hash / payload_hash / expires_at / status / result。 token_hash 是 operation_token 的摘要;subject_hash 绑定登录用户或服务端建立的 HttpOnly 匿名会话;payload_hash 绑定规范化后的关键业务参数(例如手机号、用途)。低熵会话/手机号摘要采用客户自有稳定密钥 CAPTCHA_BINDING_KEY 的 HMAC,不存明文 Token。 每个 Token 单独一行,状态初始 pending。不能用单个 session.captchaRequestId、进程内 Map 或前端隐藏字段保存唯一关联;必须支持多标签页、进程重启和多实例。 仅在关联提交成功后,向前端返回 {operation_token, expires_in},使用 Cache-Control: no-store;不返回 request_id、AK/SK 或后端状态。存储失败不得下发 Token。 3. 前端加载 ,渲染: operation_token 必须由当前业务动作临时申请;前端不设置 sitekey、mode 或 challenge。 4. CAPTCHA 通过后,前端把 captcha-token 与原业务参数提交到真实受保护业务接口(例如 POST /api/send-sms)。在该业务路由内完成身份/匿名会话、CSRF、权限、限流和参数校验,按 Token 摘要读取关联,校验同一主体、action、Origin 和业务参数,先以数据库条件更新 pending → verifying 原子抢占,再签名调用 POST https://captcha.shareapi.ai/api/v1/tokens/verify,正文必须包含: {"operation_token":"前端提交的 captcha-token","expected_action":"signup","expected_origin":"http://localhost:3100","request_id":"签发时的同一个 UUID"} 禁止提供前端可调用的独立 /captcha/verify 终验接口或通用终验代理;不能先消费 Token 再让前端另调业务,也不能信任 verified=true。Widget 自己调用的供应商 /api/v1/verify 只校验挑战答案,不能替代业务终验。 5. 只有终验 success===true 且返回的 action/origin/request_id 与存储一致,才能在客户本地同一个数据库事务中完成业务写入(或 Outbox 任务入库)以及 status=succeeded、幂等 result 保存。同 Token 并发只能有一个执行者;同主体/同参数的重复请求只能返回已有安全回执,不能再次终验或执行业务。 外部短信发送不在数据库事务内直接执行;用 request_id 作为 Outbox/下游幂等键,由现有发送逻辑消费。验证码、密码、令牌不能写入通用 result。挑战通过不是登录认证,登录仍须验证密码等业务凭据。 6. 状态与失败:明确 challenge-not-passed 表示未核销,可 verifying → pending 等用户完成;网络超时、响应丢失、响应不合法或重启遗留 verifying 必须保守拒绝,标记 unknown 或保持不可重入,不能自动重放核销或重置 pending;其他明确失败记 failed。供应商消费与客户数据库提交不是跨系统原子事务;客户事务失败后旧 Token 不可复用,需新 Token。对业务 COMMIT 结果不确定先读取已保存回执,不重做外部副作用。 保留幂等回执覆盖业务重试窗口,并用现有清理任务回收过期关联;不得误删待发送 Outbox。缺少可持久化的共享存储或真实业务路由时要明确报告尚未完成,不能只交付骨架。 7. 必须验证 localhost/测试 Origin 的真实挑战 → 实际受保护路由 → 业务落库/Outbox → 幂等回执。另覆盖错误签名、nonce 重放、Token 重放/过期、错误 action/Origin/request_id、双标签页反序提交、跨会话与更换手机号拒绝、双实例并发一次副作用、提前提交后完成挑战、核销响应丢失及业务事务回滚。mock 只用于故障注入,不能替代真实供应商验收。 8. https://captcha.shareapi.ai/monitor 的“业务终验”仅统计供应商 Token 核销成功,不代表客户短信已送达或客户事务已提交;实际业务结果沿用目标应用自己的记录与监控。 最终汇报改动文件、环境变量名、测试地址和验收结果;不得输出 CAPTCHA_SECRET_KEY 或完整 operation_token。