第 IV 部分:Sibuna 协议¶
我们按实际实现来规定线路协议:验证中间页的往返过程、无状态挑战记录、两种解答格式、验证顺序、一次性使用的强制执行,以及会话 Cookie。
挑战的往返过程¶
-
一次没有有效会话的页面导航到达策略引擎,被分类为
CHALLENGE。由于该请求接受text/html,守护进程以200返回验证中间页,并带上响应头X-Sibuna-Status: CHALLENGE;不接受 HTML 的 API 客户端则收到401和一个 JSON 响应体,其中的challengeURL 可以直接获取。无论哪种情况,响应都携带一张 要求票据:即这个决策所要求的挑战(算法、工作比特、揭示数)和规则的哈希,用该客户端自己的派生密钥计算带密钥 BLAKE3 标签加以封装,在一个挑战有效期内有效。 -
验证中间页获取
GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>。有效的票据决定挑战:工作量由要求该挑战的决策确定,而不是根据上报的 URL 和这次获取请求自身的请求头重新计算,因为这些请求头与页面导航的不同(Accept、Sec-Fetch-*)。没有有效票据时(忽略该 URL 的 API 客户端,或页面打开时间超过了有效期),服务器评估上报的 URL:用读取请求行的同一个函数把它拆分为路径和查询,并把路径转换为准入所用的规范形式(SID 0009);长度超过 8 KiB 的 URL 以414拒绝,绝不截断;没有规范形式的路径以400拒绝。票据只是建议性的:准入仍然检查会话的工作等级,因此重放或伪造的票据只会让其持有者多付出工作。 -
响应是挑战记录:
{"id":"AQEND...70 chars","algorithm":"posw","difficulty":13,"challenges":16,"expires_at":1757241234}
对于
hashcash,difficulty是比特数,challenges为0。 -
一个 Web Worker 用 WebAssembly 模块求解它;如果 WebAssembly 不可用,则使用 JavaScript 证明器(第 VII 部分)。然后它把以下两者之一
{"challenge_id":"...","nonce":"90766"}
或
{"challenge_id":"...","proof":"<base64url, 32(1 + t(n+1)) bytes>"}
提交到
POST /__sibuna/verify。 -
成功时,服务器返回
200 {"status":"ok"}并带上Set-Cookie响应头,页面随后重新加载原来的地址。之后的每个请求都携带这个 Cookie,并在策略评估之前被准入。
无状态挑战记录¶
pub fn create_challenge_with_spec(
&self,
client_ip: &[u8],
user_agent: &[u8],
now: u64,
spec: ChallengeSpec,
rule_hash: u64,
) -> Challenge {
self.adaptive.observe(now.saturating_mul(1000));
let effective = ChallengeSpec {
difficulty: spec.difficulty.saturating_add(self.adaptive.bump()),
..spec
};
let fingerprint = self.fingerprint(client_ip, user_agent);
let difficulty = effective.parameter();
let challenges = match effective.algorithm {
Algorithm::Hashcash => 0,
Algorithm::Posw => effective.posw_challenges,
};
let mut payload = [0u8; ID_PAYLOAD_LEN];
payload[0] = ID_VERSION;
payload[1] = effective.algorithm.to_byte();
payload[2] = difficulty;
payload[3] = challenges;
payload[4..12].copy_from_slice(&now.to_le_bytes());
payload[12..20].copy_from_slice(&fingerprint.to_le_bytes());
payload[20..28].copy_from_slice(&self.next_nonce(now, fingerprint).to_le_bytes());
payload[28..36].copy_from_slice(&rule_hash.to_le_bytes());
let mut raw = [0u8; ID_RAW_LEN];
raw[..ID_PAYLOAD_LEN].copy_from_slice(&payload);
raw[ID_PAYLOAD_LEN..].copy_from_slice(&self.challenge_tag(&payload));
Challenge {
id: encoded::encode(&raw),
algorithm: effective.algorithm,
difficulty,
challenges,
expires_at: now.saturating_add(u64::from(self.challenge_ttl)),
}
}
标识符是一个 Encoded<70>:文本存放在一个长度恰好相等的数组中,因此签发挑战从不分配内存。ChallengeSpec::parameter 把工作比特映射为各层自己的单位,即 Hashcash 比特数(最多 64)或 PoSW 深度(difficulty - 3,限制在 4 到 24 之间)。
有三个细节值得注意:
- 自适应难度。 协调器用三个原子变量保存挑战签发速率的指数加权移动平均。速率超过每秒 50 次挑战的基线后,速率每翻一倍就增加一个工作比特,最多增加六个。洪泛流量需要付出指数级增长的代价,而平静的流量保持基础成本。
- nonce 是 PRF 的输出,以挑战密钥为密钥,对一个计数器、时钟和指纹计算得出。它是唯一的(来自计数器)且不可预测的(来自密钥),因此对手无法为尚未签发给它的标识符预先计算解答,热路径也从不为获取熵而调用操作系统。
- 难度包含在标签之内。 客户端无法通过编辑记录来降低难度:在检查任何证明之前,标签校验就会失败。
验证顺序与一次性使用¶
pub fn verify_and_mint(
&self,
challenge_id: &[u8],
solution: Solution<'_>,
client_ip: &[u8],
user_agent: &[u8],
now: u64,
) -> Result<Verified, VerifyError> {
let record = self.decode(challenge_id)?;
let expires_at = record.issued_at.saturating_add(u64::from(self.challenge_ttl));
if now > expires_at || record.issued_at > now.saturating_add(CLOCK_SKEW_SECONDS) {
return Err(VerifyError::ChallengeExpired);
}
if record.fingerprint != self.fingerprint(client_ip, user_agent) {
return Err(VerifyError::FingerprintMismatch);
}
check_solution(challenge_id, &record, solution)?;
self.spent.mark_spent(&record.tag, expires_at, now).map_err(|error| match error {
SpendError::DoubleSpend => VerifyError::DoubleSpendAttempt,
SpendError::Full => VerifyError::StoreFull,
})?;
let work = WorkLevel {
algorithm: record.algorithm.to_byte(),
bits: record.algorithm.work_bits(record.difficulty),
};
Ok(Verified {
token: self.mint_token(now, record.rule_hash, record.fingerprint, work),
algorithm: record.algorithm,
difficulty: record.difficulty,
challenges: record.challenges,
ttl_seconds: self.token_ttl,
})
}
这个顺序是有意为之的。标签、时效和绑定都是常量时间的检查,它们在任何哈希计算之前就拒绝垃圾输入。错误的证明不能消耗挑战,因此只有在 check_solution 成功之后才写入已用集合。两个线程同时验证同一个有效解答时,会在 mark_spent 上竞争;分片锁让它们串行执行,恰好一个获胜,另一个收到 VerifyError::DoubleSpendAttempt。条件 issued_at > now + 60(CLOCK_SKEW_SECONDS 为 60)拒绝由时钟超前一分钟以上的节点签发的记录,否则这类记录会延长挑战的寿命。
错误以 400 和 Elm 风格的诊断信息(第 X 部分)呈现给客户端:每个 VerifyError 都转换为 sibuna_core::errors::ErrorKind,其说明就是响应体。端到端测试对响应体中的 DOUBLE SPEND、FINGERPRINT MISMATCH、WRONG SOLUTION TYPE 和 MALFORMED CHALLENGE 进行断言。