Das Sibuna-Handbuch 1.0.0-beta.3 Dokumentation
Sprache: Deutsch
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
Auf dieser Seite

Teil IV: Das Sibuna-Protokoll

Wir spezifizieren das Übertragungsprotokoll so, wie es implementiert ist: den Rundlauf über die Zwischenseite, den zustandslosen Challenge-Datensatz, beide Lösungsformate, die Reihenfolge der Verifikation, die Durchsetzung der Einmalverwendung und das Sitzungscookie.

Der Challenge-Rundlauf

Eine Schleife aus acht Schritten: Navigation im Browser, Zwischenseite (HTTP 200), GET /__sibuna/challenge.json?need=, zustandslose ID (Nutzlast + Tag), Lösen im Web Worker mit dem WASM- oder JS-Beweiser, POST /__sibuna/verify mit der Nonce oder dem Nachweis, Verifizieren, Verbrauchsmenge und Ausstellen des MAC-Tokens, Set-Cookie und Neuladen, dann zurück zur Navigation mit einer Sitzung.
Abb. 5 Der Challenge-Rundlauf. Die Schritte links laufen im Browser, die Schritte rechts in Sibuna.
  1. Eine Navigation ohne gültige Sitzung erreicht die Richtlinien-Engine und wird als CHALLENGE eingestuft. Weil die Anfrage text/html akzeptiert, antwortet der Daemon mit 200, der Zwischenseite und dem Header X-Sibuna-Status: CHALLENGE; ein API-Client, der kein HTML akzeptiert, erhält 401 mit einem JSON-Body, dessen URL im Feld challenge direkt abrufbar ist. In beiden Fällen trägt die Antwort ein Anforderungsticket: die Challenge, die diese Entscheidung verlangt (Algorithmus, Arbeitsbits, Öffnungen), und den Hash der Regel, für diesen Client versiegelt mit einem Tag aus BLAKE3 mit Schlüssel unter einem eigenen abgeleiteten Schlüssel und gültig für eine Challenge-Lebensdauer.

  2. Die Zwischenseite ruft GET /__sibuna/challenge.json?path=<original URL>&need=<ticket> ab. Ein gültiges Ticket bestimmt die Challenge: Die Arbeit ist durch die Entscheidung festgelegt, die sie verlangt hat, und wird nicht aus einer gemeldeten URL und den eigenen Headern des Abrufs neu berechnet, die sich von denen der Navigation unterscheiden (Accept, Sec-Fetch-*). Ohne gültiges Ticket (ein API-Client, der die URL ignoriert, eine Seite, die über die Lebensdauer hinaus offen blieb) wertet der Server die gemeldete URL aus. Er zerlegt sie mit derselben Funktion, die die Anfragezeile liest, in Pfad und Query und bringt den Pfad in die Normalform, die die Zulassung verwendet (SID 0009); eine URL, die länger als 8 KiB ist, wird mit 414 abgewiesen, nie gekürzt, und ein Pfad ohne Normalform mit 400. Das Ticket ist nur ein Hinweis: Die Zulassung prüft weiterhin die Arbeitsstufe der Sitzung, sodass ein wiederholtes oder gefälschtes Ticket seinen Inhaber nur Arbeit kosten kann.

  3. Die Antwort ist der Challenge-Datensatz:

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

    Für hashcash ist difficulty die Bitzahl und challenges ist 0.

  4. Ein Web Worker löst sie mit dem WebAssembly-Modul oder, wenn WebAssembly nicht verfügbar ist, mit dem JavaScript-Beweiser (Teil VII) und sendet entweder

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

    oder

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

    an POST /__sibuna/verify.

  5. Bei Erfolg antwortet der Server mit 200 {"status":"ok"} und einem Set-Cookie-Header, und die Seite lädt ihre ursprüngliche Adresse neu. Jede spätere Anfrage trägt das Cookie und wird vor der Richtlinienauswertung zugelassen.

Der zustandslose Challenge-Datensatz

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)),
    }
}

Die Kennung ist ein Encoded<70>: Der Text liegt in einem Array von genau seiner Länge, sodass das Ausstellen einer Challenge nie allokiert. ChallengeSpec::parameter bildet Arbeitsbits auf die eigene Einheit der Stufe ab, Hashcash-Bits (höchstens 64) oder PoSW-Tiefe (difficulty - 3, begrenzt auf 4 bis 24).

Drei Details verdienen Aufmerksamkeit:

  • Adaptive Schwierigkeit. Der Koordinator führt einen exponentiell gewichteten gleitenden Mittelwert der Challenge-Ausgaberate in drei atomaren Variablen. Oberhalb einer Grundrate von 50 Challenges pro Sekunde fügt jede Verdopplung der Rate ein Arbeitsbit hinzu, höchstens sechs. Eine Flut zahlt exponentiell mehr, während ruhiger Datenverkehr die Grundkosten behält.
  • Die Nonce ist eine PRF-Ausgabe, mit dem Challenge-Schlüssel über einen Zähler, die Uhr und den Fingerabdruck berechnet. Sie ist eindeutig (Zähler) und unvorhersagbar (Schlüssel), sodass ein Gegner keine Lösungen für Kennungen vorberechnen kann, die ihm nicht ausgestellt wurden, und der Hot Path nie das Betriebssystem nach Entropie fragt.
  • Die Schwierigkeit reist im Tag mit. Ein Client kann die Schwierigkeit nicht senken, indem er den Datensatz bearbeitet: Die Prüfung des Tags würde scheitern, bevor irgendein Nachweis untersucht wird.

Reihenfolge der Verifikation und Einmalverwendung

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,
    })
}

Die Reihenfolge ist Absicht. Tag, Alter und Bindung sind Prüfungen in konstanter Zeit, die unbrauchbare Eingaben vor jedem Hashen abweisen. Ein falscher Nachweis darf die Challenge nicht verbrauchen, daher wird die Verbrauchsmenge erst beschrieben, nachdem check_solution erfolgreich war. Zwei Threads, die beide dieselbe gültige Lösung verifizieren, liefern sich bei mark_spent einen Wettlauf; die Shard-Sperre serialisiert sie, genau einer gewinnt, und der andere erhält VerifyError::DoubleSpendAttempt. Die Klausel issued_at > now + 60 (CLOCK_SKEW_SECONDS ist 60) weist Datensätze ab, die ein Knoten ausgestellt hat, dessen Uhr um mehr als eine Minute vorgeht; sonst würde sich die Lebensdauer einer Challenge verlängern.

Fehler erreichen den Client als 400 mit einer Diagnose im Elm-Stil (Teil X): Jeder VerifyError wird in sibuna_core::errors::ErrorKind umgewandelt, dessen Erklärung der Antwort-Body ist. Die End-to-End-Tests prüfen den Antwort-Body auf DOUBLE SPEND, FINGERPRINT MISMATCH, WRONG SOLUTION TYPE und MALFORMED CHALLENGE.