DOCUMENTATION · V2
后端掌握凭据,
前端只用一次性 Token。
客户业务后端使用 AK/SK 签名申请短时操作 Token,浏览器只用该 Token 完成挑战;提交业务时,客户后端再以 AK/SK 验证并原子消费 Token。接入不依赖生产域名验证。
完整接入流程
- 后端申请并落库使用 AK/SK 申请 Token,保存 request_id、action、Origin、会话和业务参数关联,再向浏览器返回 Token。
- 前端完成挑战业务后端把 operation_token 下发给浏览器,Widget 使用它加载并完成服务端指定题型。
- 提交业务请求浏览器把同一个 operation_token 随注册、登录或发送短信请求提交给业务后端。
- 业务路由终验并提交后端按 Token 取回关联、原子抢占并签名终验;成功后在本地事务中保存业务与幂等回执。
AK/SK 只属于客户后端
Access Key 标识独立应用,Secret Key 用于请求签名。两者都不得下发前端;Secret Key 只在创建应用时显示一次。建议先签发测试凭据,在 localhost 或预发布 Origin 完成真实闭环,再签发生产凭据。
公共演示凭据
仅用于本地协议冒烟和首页演示,不进入客户监控。真实项目应使用生成器签发的独立测试 AK/SK。
- 测试 AK
site_test_shareapi_public- 测试 SK
secret_test_shareapi_public
请求签名
签名覆盖实际发送的原始 JSON 正文、方法、路径、时间戳和随机 nonce。服务允许最多 5 分钟时钟偏差;同一 AK 下 nonce 只能使用一次。
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
};
}签发一次性操作 Token
Token 默认 5 分钟有效,且 request_id 在同一 AK 下唯一。浏览器没有 AK/SK,必须通过自己的业务后端获取 Token。
// 后端模块;完整实现下载 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。后端必须保存每个 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、业务参数与权限校验、短信限流继续由客户业务接口执行。
前端 Widget
组件是 form-associated Custom Element。设置新的 token 属性会加载挑战;验证成功后,同一个操作 Token 会写入 name 对应的表单字段。
<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 流程忽略客户端降级意图,题型由服务端策略决定。 |
生产题型由服务端决定
Token 已绑定 AK 与 action。注册、登录等常规动作默认使用拼图;send_sms、账号找回、提现、兑换和投票等高风险动作默认使用障碍躲避。前端不能通过参数改成更弱题型。
| 题型 | 生产素材与变化量 | 服务端约束 |
|---|---|---|
puzzle | 100 个真实场景,每场景至少 8 个动态缺口。 | 答案只保存在 PostgreSQL;题面与裁片只返回 WebP。 |
icons | 30 类 × 20 个真实对象变体;每题动态布局 6–9 个对象。 | 按服务端随机提示顺序验证三个命中位置。 |
dodge | 30 个真实场景 × 8 套可解布局 × 5 个任务角色。 | 联合验证路线、碰撞、时长、密度、检查点和非匀速节奏。 |
验证并消费操作 Token
终验位于真实受保护路由内部,例如 POST /api/send-sms。先验证当前主体和业务参数,再按 Token 摘要原子抢占 pending → verifying,取出原 request_id 调用供应商终验。绑定错误不会消费供应商 Token;正确核销只能成功一次。
// 同一后端模块,由真实 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 核销成功,不表示短信送达或客户事务成功。
下载参考代码并验收真实业务路径
参考代码包含可执行签名、PostgreSQL 关联、并发抢占、事务、Outbox 和幂等回执。先在客户自己的测试数据库与 localhost 运行,再把 gate 接入现有真实业务路由;生产使用现有认证、CSRF、限流和发送器。
后端 gate · 数据库迁移 · 本地验收服务 · 验收页面
# 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 不得提前删除。
交给编码 Agent 的提示词
所有者在生成器中填写应用、测试或生产环境、Origins 与 actions,系统签发独立 AK/SK 并生成提示词。提示词包含 AK 和完整协议,但不包含 SK;SK 只通过安全渠道交给获授权 Agent。
已有 AK/SK 无需重新签发:下载当前提示词模板,替换为已有应用的环境、Origin、action,并让 Agent 按 customer-business-gate-v1 补齐关联和业务路由。
接口参考
| 接口 | 调用方 | 用途 |
|---|---|---|
POST /api/v1/tokens/issue | 客户后端 | 使用 AK/SK 签名申请 5 分钟操作 Token。 |
GET /api/v1/challenge | Widget | 使用 X-Captcha-Token 获取来源/action 绑定挑战。 |
POST /api/v1/challenge/:id/checkpoint | Widget | 提交路线题内部行为检查点。 |
POST /api/v1/verify | Widget | 验证答案并把对应操作 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 状态存储。 |
关键错误码
missing-auth缺少 AK/SK 签名请求头。
invalid-authAK、签名或签名格式无效。
expired-auth签名时间戳超出允许偏差。
replayed-auth同一 AK 下重复使用了 nonce。
duplicate-request-id同一 AK 已使用该业务请求 ID。
missing-operation-token客户 Widget 未获得操作 Token。
challenge-not-passedToken 尚未完成 CAPTCHA 挑战。
action-mismatchaction 与 Token 绑定不一致。
origin-mismatchOrigin 与 Token 绑定不一致。
request-id-mismatch业务请求 ID 与签发记录不一致。
timeout-or-duplicateToken 已过期、不属于该 AK 或已被消费。
invalid-solution挑战答案、顺序或路线未通过。
invalid-behavior路线行为检查未通过。
rate-limited请求超过当前限额。
生产安全要求
- AK/SK 只保存在客户业务后端;尤其不能把 SK 写入浏览器、移动 App 或公开仓库。
- 签名必须覆盖实际发送的 raw JSON,不要签名后重新序列化正文。
- 每次签名使用新的随机 nonce,并保持服务器时间同步。
- Token 必须按 action、Origin 和 request_id 终验,且只在 success=true 后执行业务。
- 为不同关键动作使用稳定 action;不要把 mode/challenge 当成生产安全配置。
- 把 CAPTCHA 与 WAF、接口限流、账号信誉、设备风险和业务幂等共同使用。