Sibuna 之书 1.0.0-beta.3 文档
语言: 简体中文
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
本页内容

第 IV 部分:Sibuna 协议

我们按实际实现来规定线路协议:验证中间页的往返过程、无状态挑战记录、两种解答格式、验证顺序、一次性使用的强制执行,以及会话 Cookie。

挑战的往返过程

一个八步循环:浏览器导航;验证中间页(HTTP 200);GET /__sibuna/challenge.json?need=;无状态 ID(载荷 + 标签);Web Worker 用 WASM 或 JS 证明器求解;携带 nonce 或证明的 POST /__sibuna/verify;验证、写入已用集合并签发 MAC 令牌;Set-Cookie 后重新加载;最后带着会话回到导航。
图 5 挑战的往返过程。左侧的步骤在浏览器中运行,右侧的步骤在 Sibuna 中运行。
  1. 一次没有有效会话的页面导航到达策略引擎,被分类为 CHALLENGE。由于该请求接受 text/html,守护进程以 200 返回验证中间页,并带上响应头 X-Sibuna-Status: CHALLENGE;不接受 HTML 的 API 客户端则收到 401 和一个 JSON 响应体,其中的 challenge URL 可以直接获取。无论哪种情况,响应都携带一张 要求票据:即这个决策所要求的挑战(算法、工作比特、揭示数)和规则的哈希,用该客户端自己的派生密钥计算带密钥 BLAKE3 标签加以封装,在一个挑战有效期内有效。

  2. 验证中间页获取 GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>。有效的票据决定挑战:工作量由要求该挑战的决策确定,而不是根据上报的 URL 和这次获取请求自身的请求头重新计算,因为这些请求头与页面导航的不同(Accept、Sec-Fetch-*)。没有有效票据时(忽略该 URL 的 API 客户端,或页面打开时间超过了有效期),服务器评估上报的 URL:用读取请求行的同一个函数把它拆分为路径和查询,并把路径转换为准入所用的规范形式(SID 0009);长度超过 8 KiB 的 URL 以 414 拒绝,绝不截断;没有规范形式的路径以 400 拒绝。票据只是建议性的:准入仍然检查会话的工作等级,因此重放或伪造的票据只会让其持有者多付出工作。

  3. 响应是挑战记录:

    {"id":"AQEND...70 chars","algorithm":"posw","difficulty":13,"challenges":16,"expires_at":1757241234}
    

    对于 hashcash,difficulty 是比特数,challenges 为 0。

  4. 一个 Web Worker 用 WebAssembly 模块求解它;如果 WebAssembly 不可用,则使用 JavaScript 证明器(第 VII 部分)。然后它把以下两者之一

    {"challenge_id":"...","nonce":"90766"}
    

    或

    {"challenge_id":"...","proof":"<base64url, 32(1 + t(n+1)) bytes>"}
    

    提交到 POST /__sibuna/verify。

  5. 成功时,服务器返回 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 进行断言。