DOCUMENTATION · V2

后端掌握凭据,
前端只用一次性 Token。

客户业务后端使用 AK/SK 签名申请短时操作 Token,浏览器只用该 Token 完成挑战;提交业务时,客户后端再以 AK/SK 验证并原子消费 Token。接入不依赖生产域名验证。

REQUEST FLOW

完整接入流程

  1. 后端申请并落库使用 AK/SK 申请 Token,保存 request_id、action、Origin、会话和业务参数关联,再向浏览器返回 Token。
  2. 前端完成挑战业务后端把 operation_token 下发给浏览器,Widget 使用它加载并完成服务端指定题型。
  3. 提交业务请求浏览器把同一个 operation_token 随注册、登录或发送短信请求提交给业务后端。
  4. 业务路由终验并提交后端按 Token 取回关联、原子抢占并签名终验;成功后在本地事务中保存业务与幂等回执。
SERVER CREDENTIALS

AK/SK 只属于客户后端

Access Key 标识独立应用,Secret Key 用于请求签名。两者都不得下发前端;Secret Key 只在创建应用时显示一次。建议先签发测试凭据,在 localhost 或预发布 Origin 完成真实闭环,再签发生产凭据。

登录并签发 AK/SK ↗测试与生产凭据、数据和 Origin 白名单相互隔离。
PUBLIC SMOKE TEST

公共演示凭据

仅用于本地协议冒烟和首页演示,不进入客户监控。真实项目应使用生成器签发的独立测试 AK/SK。

测试 AK
site_test_shareapi_public
测试 SK
secret_test_shareapi_public
HMAC AUTHENTICATION

请求签名

签名覆盖实际发送的原始 JSON 正文、方法、路径、时间戳和随机 nonce。服务允许最多 5 分钟时钟偏差;同一 AK 下 nonce 只能使用一次。

captcha-signature.js
import { createHash, createHmac, randomBytes } from 'node:crypto';

function signedHeaders(pathname, rawBody) {
  const timestamp = Math.floor(Date.now() / 1000);
  const nonce = randomBytes(18).toString('base64url');
  const bodyHash = createHash('sha256').update(rawBody).digest('base64url');
  const signingKey = createHash('sha256')
    .update(process.env.CAPTCHA_SECRET_KEY)
    .digest('base64url');
  const canonical = [
    'SHAREAPI-CAPTCHA-HMAC-SHA256', 'POST', pathname,
    timestamp, nonce, bodyHash
  ].join('\n');
  const signature = createHmac('sha256', signingKey)
    .update(canonical).digest('base64url');
  return {
    'Content-Type': 'application/json',
    'X-Captcha-AK': process.env.CAPTCHA_ACCESS_KEY,
    'X-Captcha-Timestamp': String(timestamp),
    'X-Captcha-Nonce': nonce,
    'X-Captcha-Signature': signature
  };
}
SERVER · STEP 1

签发一次性操作 Token

Token 默认 5 分钟有效,且 request_id 在同一 AK 下唯一。浏览器没有 AK/SK,必须通过自己的业务后端获取 Token。

server-issue.js
// 后端模块;完整实现下载 customer-gate.mjs。
import pg from 'pg';
import { createCaptchaGate } from './customer-gate.mjs';
const gate = createCaptchaGate({
  pool: new pg.Pool({ connectionString: process.env.CUSTOMER_DATABASE_URL }),
  accessKey: process.env.CAPTCHA_ACCESS_KEY,
  secretKey: process.env.CAPTCHA_SECRET_KEY,
  bindingKey: process.env.CAPTCHA_BINDING_KEY
});

// 由 POST /api/captcha/token 调用;先完成会话、CSRF、限流和手机号校验。
export async function issueSmsCaptcha({ sessionId, validatedPhone }) {
  return gate.issue({
    action: 'send_sms',
    origin: 'http://localhost:3100', // 生产使用后端配置的允许 Origin
    subject: sessionId, // 已验证登录主体或服务端 HttpOnly 匿名会话
    payload: { phone: validatedPhone, purpose: 'login' }
  });
}
// gate 内生成 request_id 并持久化每个 Token 的关联;落库成功后只返回
// { operation_token, expires_in }。HTTP 响应使用 Cache-Control: no-store。
CUSTOMER BUSINESS GATE · V1

后端必须保存每个 Token 的业务关联

request_id 在后端生成一次,签发和终验复用。浏览器只接收 operation_token 与 expires_in;后端凭 Token 摘要查询关联,不让前端传回或决定 request_id。使用目标应用已有数据库或持久化共享存储,多标签页、多进程和多实例共用同一状态。

字段后端用途
token_hash / request_id每 Token 独立一行;Token 只存摘要,request_id 唯一且不可在终验时重新生成。
action / origin从真实业务路由及允许的 Origin 配置选取,并验证实际来源。
subject_hash / payload_hash绑定当前登录或匿名会话及规范化业务参数。手机号/邮箱等低熵数据用客户独立密钥 HMAC。
expires_at / status / result控制有效期、原子消费、失败和幂等回执;result 不含验证码、密码或 Token。

关联提交成功后才能下发 Token。不要使用单个 session.captchaRequestId 或进程内 Map;它们会丢失并发标签页和多实例的关联。登录态、CSRF、业务参数与权限校验、短信限流继续由客户业务接口执行。

BROWSER · STEP 2

前端 Widget

组件是 form-associated Custom Element。设置新的 token 属性会加载挑战;验证成功后,同一个操作 Token 会写入 name 对应的表单字段。

index.html
<script type="module"
  src="https://captcha.shareapi.ai/captcha.js"></script>

<shareapi-captcha id="captcha"
  action="send_sms"
  name="captcha-token"
  required>
</shareapi-captcha>

<script type="module">
  // 手机号需与随后提交的业务参数一致;改变手机号必须重新申请 Token。
  const issued = await fetch('/api/captcha/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone: '13800000000' })
  }).then(r => r.json());
  document.querySelector('#captcha')
    .setAttribute('token', issued.operation_token);
</script>
属性必需说明
token生产必需由客户后端临时申请的一次性 operation_token。
action必需必须与 Token 签发时绑定的 action 完全一致。
name否表单字段名,默认 captcha-response。
sitekey演示专用只为公共演示模式保留;客户生产接入不得使用。
mode / challenge演示专用生产 Token 流程忽略客户端降级意图,题型由服务端策略决定。
SERVER-ENFORCED POLICY

生产题型由服务端决定

Token 已绑定 AK 与 action。注册、登录等常规动作默认使用拼图;send_sms、账号找回、提现、兑换和投票等高风险动作默认使用障碍躲避。前端不能通过参数改成更弱题型。

题型生产素材与变化量服务端约束
puzzle100 个真实场景,每场景至少 8 个动态缺口。答案只保存在 PostgreSQL;题面与裁片只返回 WebP。
icons30 类 × 20 个真实对象变体;每题动态布局 6–9 个对象。按服务端随机提示顺序验证三个命中位置。
dodge30 个真实场景 × 8 套可解布局 × 5 个任务角色。联合验证路线、碰撞、时长、密度、检查点和非匀速节奏。
SERVER · STEP 3

验证并消费操作 Token

终验位于真实受保护路由内部,例如 POST /api/send-sms。先验证当前主体和业务参数,再按 Token 摘要原子抢占 pending → verifying,取出原 request_id 调用供应商终验。绑定错误不会消费供应商 Token;正确核销只能成功一次。

server-verify.js
// 同一后端模块,由真实 POST /api/send-sms 调用;没有独立 /captcha/verify。
export async function submitSms({ sessionId, validatedPhone, operationToken }) {
  const payload = { phone: validatedPhone, purpose: 'login' };
  return gate.execute({
    operationToken, subject: sessionId, payload,
    action: 'send_sms', origin: 'http://localhost:3100'
  }, async (client, { requestId }) => {
    // gate 已从持久化关联取回同一 request_id,原子抢占并通过供应商终验。
    // 只在本地事务内写业务数据或 Outbox,不在这里调用外部短信服务。
    await client.query(
      'INSERT INTO customer_captcha_outbox (request_id, action, payload) VALUES ($1,$2,$3)',
      [requestId, 'send_sms', JSON.stringify(payload)]
    );
    return { accepted: true, job_id: requestId };
  });
}
// gate 将业务写入、succeeded 状态和安全回执放在同一事务中提交。
// 同主体/同参数的重复请求返回已保存回执,不再次核销或发送。

不能暴露供前端单独调用的 /captcha/verify 核销代理,也不能信任前端传入的 verified=true。Widget 调用的供应商 /api/v1/verify 仅校验挑战答案,不是业务终验。

结果客户后端处理
明确 challenge-not-passed尚未核销,可恢复 pending,等本次挑战通过后提交。
成功且响应绑定一致事务内写业务数据/Outbox、succeeded 和回执;重复请求只读回执。
业务事务失败回滚业务写入并标记 failed;已核销 Token 不可复用。
超时、响应丢失、进程中断标记 unknown 或保持 verifying,禁止自动重验和重置 pending;先查已提交回执,必要时重新挑战。
两系统的事务边界

供应商核销与客户业务提交不是同一个跨系统事务。外部短信先写 Outbox,使用 request_id 作为下游幂等键;不要在数据库事务内直接发送。当前监控中的“业务终验”只表示 CAPTCHA 核销成功,不表示短信送达或客户事务成功。

RUNNABLE CUSTOMER REFERENCE

下载参考代码并验收真实业务路径

参考代码包含可执行签名、PostgreSQL 关联、并发抢占、事务、Outbox 和幂等回执。先在客户自己的测试数据库与 localhost 运行,再把 gate 接入现有真实业务路由;生产使用现有认证、CSRF、限流和发送器。

后端 gate · 数据库迁移 · 本地验收服务 · 验收页面

localhost acceptance
# Node.js 22+,复用客户自己的 PostgreSQL;无需部署 CAPTCHA 服务端。
# 在独立示例目录执行;环境变量通过后端 Secret 管理提供,禁止提交 .env。
for file in customer-gate.mjs customer-schema.sql customer-demo.mjs customer-demo.html; do
  curl -fsS "https://captcha.shareapi.ai/integration/$file" -o "$file"
done
npm install pg
psql "$CUSTOMER_DATABASE_URL" -v ON_ERROR_STOP=1 -f customer-schema.sql
# 配置 CUSTOMER_DATABASE_URL、CAPTCHA_ACCESS_KEY、CAPTCHA_SECRET_KEY、
# CAPTCHA_BINDING_KEY(客户生成的至少 32 字符随机密钥,跨实例稳定)。
# 测试凭据的 Origin 必须包含 http://localhost:3100,或设置匹配的 PORT。
node customer-demo.mjs
# 打开 http://localhost:3100;完成挑战后提交业务并检查 Outbox 只有一条记录。
# 示例只接收任务,不发送真实短信;生产接入现有发送器及下游幂等键。
  • 真实挑战 → 业务路由 → 业务写入/Outbox → 幂等回执,不能只以编译成功或 mock 通过验收。
  • 双标签页反序提交、应用重启后继续、双实例同时提交:每 Token 最多一条业务记录。
  • 其他会话盗用、更换手机号、错误 action/Origin/request_id、缺失 Token 均拒绝,原有效关联不被误消费。
  • 提前提交后可继续完成挑战;核销超时、响应丢失和业务事务回滚不能放行业务或重用旧 Token。
  • 回执按业务重试窗口保留(例如 24 小时),过期关联由现有清理任务回收,未完成 Outbox 不得提前删除。
AI INTEGRATION PROMPT

交给编码 Agent 的提示词

所有者在生成器中填写应用、测试或生产环境、Origins 与 actions,系统签发独立 AK/SK 并生成提示词。提示词包含 AK 和完整协议,但不包含 SK;SK 只通过安全渠道交给获授权 Agent。

打开凭据与提示词生成器 ↗不需要修改生产站点,也不需要部署临时验证文件。

已有 AK/SK 无需重新签发:下载当前提示词模板,替换为已有应用的环境、Origin、action,并让 Agent 按 customer-business-gate-v1 补齐关联和业务路由。

API REFERENCE

接口参考

接口调用方用途
POST /api/v1/tokens/issue客户后端使用 AK/SK 签名申请 5 分钟操作 Token。
GET /api/v1/challengeWidget使用 X-Captcha-Token 获取来源/action 绑定挑战。
POST /api/v1/challenge/:id/checkpointWidget提交路线题内部行为检查点。
POST /api/v1/verifyWidget验证答案并把对应操作 Token 标记为挑战通过。
POST /api/v1/tokens/verify客户后端使用 AK/SK 签名验证并原子消费操作 Token。
POST /api/v1/admin/applications所有者生成器登录后签发应用 AK/SK 和 Agent 提示词。
GET /api/v1/admin/metrics所有者监控读取按 AK、action、Origin 与题型聚合的小时指标。
GET /api/v1/health监控检查应用与 PostgreSQL 状态存储。
ERRORS

关键错误码

missing-auth

缺少 AK/SK 签名请求头。

invalid-auth

AK、签名或签名格式无效。

expired-auth

签名时间戳超出允许偏差。

replayed-auth

同一 AK 下重复使用了 nonce。

duplicate-request-id

同一 AK 已使用该业务请求 ID。

missing-operation-token

客户 Widget 未获得操作 Token。

challenge-not-passed

Token 尚未完成 CAPTCHA 挑战。

action-mismatch

action 与 Token 绑定不一致。

origin-mismatch

Origin 与 Token 绑定不一致。

request-id-mismatch

业务请求 ID 与签发记录不一致。

timeout-or-duplicate

Token 已过期、不属于该 AK 或已被消费。

invalid-solution

挑战答案、顺序或路线未通过。

invalid-behavior

路线行为检查未通过。

rate-limited

请求超过当前限额。

SECURITY

生产安全要求

  • AK/SK 只保存在客户业务后端;尤其不能把 SK 写入浏览器、移动 App 或公开仓库。
  • 签名必须覆盖实际发送的 raw JSON,不要签名后重新序列化正文。
  • 每次签名使用新的随机 nonce,并保持服务器时间同步。
  • Token 必须按 action、Origin 和 request_id 终验,且只在 success=true 后执行业务。
  • 为不同关键动作使用稳定 action;不要把 mode/challenge 当成生产安全配置。
  • 把 CAPTCHA 与 WAF、接口限流、账号信誉、设备风险和业务幂等共同使用。