Documentación de El libro de Sibuna 1.0.0-beta.3
Idioma: Español
English简体中文한국어日本語EspañolDeutschहिन्दीالعربية
En esta página

Parte IV: El protocolo de Sibuna

Especificamos el protocolo de comunicación tal como está implementado: el intercambio con la página intermedia, el registro de desafío sin estado, los dos formatos de solución, el orden de verificación, la garantía de uso único y la cookie de sesión.

El intercambio del desafío

Un ciclo de ocho pasos: navegación del navegador, página intermedia (HTTP 200), GET /__sibuna/challenge.json?need=, identificador sin estado (carga útil + etiqueta), resolución en un Web Worker con el probador WASM o JS, POST /__sibuna/verify con el nonce o la prueba, verificación, conjunto de desafíos gastados y emisión del token MAC, Set-Cookie y recarga, y vuelta a la navegación, ya con una sesión.
Fig. 5 El intercambio del desafío. Los pasos de la izquierda se ejecutan en el navegador, y los de la derecha, en Sibuna.
  1. Una navegación sin sesión válida llega al motor de políticas y se clasifica como CHALLENGE. Como la petición acepta text/html, el daemon responde 200 con la página intermedia y la cabecera X-Sibuna-Status: CHALLENGE; un cliente de API que no acepta HTML recibe 401 con un cuerpo JSON cuya URL challenge ya puede pedirse. En ambos casos la respuesta lleva un ticket de requisito: el desafío que exige esta decisión (algoritmo, bits de trabajo, aperturas) y el hash de la regla, sellados para este cliente con una etiqueta BLAKE3 calculada con su propia clave derivada y válidos durante el tiempo de vida de un desafío.

  2. La página intermedia pide GET /__sibuna/challenge.json?path=<original URL>&need=<ticket>. Un ticket válido decide el desafío: el trabajo lo fija la decisión que lo exigió, y no se recalcula a partir de la URL que comunica la página ni de las cabeceras de esta segunda petición, que difieren de las de la navegación (Accept, Sec-Fetch-*). Sin un ticket válido (un cliente de API que ignora la URL, una página que sigue abierta más allá del tiempo de vida) el servidor evalúa la URL comunicada, que la misma función que lee la línea de petición divide en ruta y consulta, con la ruta en la forma normal que usa la admisión (SID 0009); una URL de más de 8 KiB se rechaza con 414, nunca se trunca, y una ruta sin forma normal, con 400. El ticket es orientativo: la admisión sigue comprobando el nivel de trabajo de la sesión, así que un ticket reutilizado o falsificado solo puede costar trabajo a quien lo presenta.

  3. La respuesta es el registro de desafío:

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

    Para hashcash, difficulty es el número de bits y challenges vale 0.

  4. Un Web Worker lo resuelve con el módulo WebAssembly, o con el probador JavaScript si WebAssembly no está disponible (parte VII), y envía o bien

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

    o bien

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

    a POST /__sibuna/verify.

  5. Si la verificación tiene éxito, el servidor responde 200 {"status":"ok"} con una cabecera Set-Cookie, y la página recarga su ubicación original. Cada petición posterior lleva la cookie y se admite antes de evaluar las políticas.

El registro de desafío sin estado

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

El identificador es un Encoded<70>: el texto se guarda en un array de su longitud exacta, así que emitir un desafío nunca asigna memoria. ChallengeSpec::parameter convierte los bits de trabajo en la unidad propia de cada nivel: bits de Hashcash (como máximo 64) o profundidad de PoSW (difficulty - 3, limitada al intervalo de 4 a 24).

Tres detalles merecen atención:

  • Dificultad adaptativa. El coordinador mantiene en tres atómicos una media móvil con ponderación exponencial de la tasa de emisión de desafíos. Por encima de una base de 50 desafíos por segundo, cada duplicación de la tasa añade un bit de trabajo, hasta un máximo de seis. Una inundación paga un coste exponencialmente mayor, mientras que el tráfico tranquilo mantiene el coste base.
  • El nonce es la salida de una PRF con la clave de desafíos, calculada sobre un contador, el reloj y la huella. Es único (por el contador) e impredecible (por la clave), así que un adversario no puede precalcular soluciones para identificadores que no se le han emitido, y la ruta crítica nunca llama al sistema operativo para obtener entropía.
  • La dificultad viaja dentro de la etiqueta. Un cliente no puede reducir la dificultad editando el registro: la etiqueta fallaría antes de examinar ninguna prueba.

Orden de verificación y uso único

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

El orden es deliberado. La etiqueta, la antigüedad y el vínculo son comprobaciones en tiempo constante que descartan la basura antes de calcular ningún hash. Una prueba errónea no debe consumir el desafío, así que el conjunto de desafíos gastados solo se escribe después de que check_solution tenga éxito. Dos hilos que verifican la misma solución válida compiten en mark_spent; el cerrojo de la partición los serializa, exactamente uno gana y el otro recibe VerifyError::DoubleSpendAttempt. La cláusula issued_at > now + 60 (CLOCK_SKEW_SECONDS vale 60) rechaza los registros emitidos por un nodo cuyo reloj va adelantado más de un minuto, que de otro modo alargarían la vida de un desafío.

Los errores llegan al cliente como 400 con un diagnóstico al estilo de Elm (parte X): cada VerifyError se convierte en un sibuna_core::errors::ErrorKind, cuya explicación es el cuerpo de la respuesta. Las pruebas de extremo a extremo comprueban DOUBLE SPEND, FINGERPRINT MISMATCH, WRONG SOLUTION TYPE y MALFORMED CHALLENGE en el cuerpo de la respuesta.