termo_core 0.1.13

Todos os clientes da Termotubos num crate só: um módulo por serviço e cada rota da API como uma função de uma linha, com o endereço resolvido pelo ambiente atual.
Documentation
use std::collections::HashMap;
use std::error::Error;
use std::fmt;
use std::sync::{LazyLock, OnceLock, RwLock};
use std::time::{Duration, Instant};

use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use base64::Engine;
use http::{HeaderMap, StatusCode};
use reqwest::{redirect::Policy, Client};
use serde::Deserialize;
use tokio::sync::Mutex;
use uuid::Uuid;

use crate::webhook::assinatura::{
    assinatura_da_entrega_confere, data_dentro_da_janela, endereco_do_termo_webhook_no_ambiente_atual, CABECALHO_ASSINATURA, CABECALHO_CHAVE,
    CABECALHO_DATA, CAMINHO_DAS_CHAVES_PUBLICAS,
};
use crate::webhook::eventos::{Evento, EventoRecebido};

const TEMPO_LIMITE_EM_SEGUNDOS: u64 = 10;

const INTERVALO_MINIMO_ENTRE_BUSCAS: Duration = Duration::from_secs(30);

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConfiguracaoDeRecebimento {
    pub url: String,
    pub aplicativo_id: String,
}

impl ConfiguracaoDeRecebimento {
    pub fn nova(url: impl Into<String>, aplicativo_id: impl Into<String>) -> Self {
        Self {
            url: url.into().trim().trim_end_matches('/').to_string(),
            aplicativo_id: aplicativo_id.into(),
        }
    }

    pub async fn carregar_do_ambiente_atual() -> Result<Self, ErroDeRecebimento> {
        let aplicativo_id = crate::base::token_do_aplicativo::identificador_do_aplicativo()
            .await
            .map_err(|erro| ErroDeRecebimento::SemIdentificacaoDoAplicativo(erro.to_string()))?;
        Ok(Self::nova(endereco_do_termo_webhook_no_ambiente_atual(), aplicativo_id))
    }

    pub fn endereco_das_chaves(&self) -> String {
        format!("{}{CAMINHO_DAS_CHAVES_PUBLICAS}", self.url)
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErroDeRecebimento {
    SemIdentificacaoDoAplicativo(String),
    SemAssinatura,
    ForaDaJanela,
    ChaveDesconhecida(String),
    ChavesIndisponiveis(String),
    AssinaturaInvalida,
    CorpoInvalido(String),
    TipoDiferente { tipo: String, versao: i32 },
}

impl ErroDeRecebimento {
    pub fn status(&self) -> StatusCode {
        match self {
            Self::SemAssinatura | Self::ForaDaJanela | Self::ChaveDesconhecida(_) | Self::AssinaturaInvalida => {
                StatusCode::UNAUTHORIZED
            }
            Self::SemIdentificacaoDoAplicativo(_) | Self::ChavesIndisponiveis(_) => StatusCode::SERVICE_UNAVAILABLE,
            Self::CorpoInvalido(_) => StatusCode::BAD_REQUEST,
            Self::TipoDiferente { .. } => StatusCode::OK,
        }
    }
}

impl fmt::Display for ErroDeRecebimento {
    fn fmt(&self, formatador: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::SemIdentificacaoDoAplicativo(mensagem) => write!(
                formatador,
                "não foi possível saber o id do app no TermoAuth pelo token de aplicativo: {mensagem}"
            ),
            Self::SemAssinatura => write!(
                formatador,
                "entrega sem os cabeçalhos X-TermoWebhook-Data, X-TermoWebhook-Chave e X-TermoWebhook-Assinatura"
            ),
            Self::ForaDaJanela => write!(formatador, "X-TermoWebhook-Data fora da tolerância de 5 minutos"),
            Self::ChaveDesconhecida(chave) => write!(formatador, "chave {chave} não está entre as chaves públicas do hub"),
            Self::ChavesIndisponiveis(mensagem) => {
                write!(formatador, "não foi possível buscar as chaves públicas do hub: {mensagem}")
            }
            Self::AssinaturaInvalida => write!(
                formatador,
                "assinatura não confere com a chave do hub para este aplicativo"
            ),
            Self::CorpoInvalido(mensagem) => write!(formatador, "corpo da entrega inválido: {mensagem}"),
            Self::TipoDiferente { tipo, versao } => write!(formatador, "evento {tipo} v{versao} não é o esperado"),
        }
    }
}

impl Error for ErroDeRecebimento {}

#[derive(Deserialize)]
struct Identificacao {
    id: Uuid,
    tipo: String,
    versao: i32,
}

#[derive(Deserialize)]
struct ChavePublica {
    kid: String,
    x: String,
}

#[derive(Deserialize)]
struct ConjuntoDeChaves {
    keys: Vec<ChavePublica>,
}

#[derive(Debug, Clone)]
pub struct Entrega<'a> {
    corpo: &'a [u8],
    pub id: Uuid,
    pub tipo: String,
    pub versao: i32,
}

impl<'a> Entrega<'a> {
    pub fn e<T: Evento>(&self) -> bool {
        self.tipo == T::TIPO && self.versao == T::VERSAO
    }

    pub fn ler<T: Evento>(&self) -> Result<EventoRecebido<T>, ErroDeRecebimento> {
        if !self.e::<T>() {
            return Err(ErroDeRecebimento::TipoDiferente {
                tipo: self.tipo.clone(),
                versao: self.versao,
            });
        }

        serde_json::from_slice(self.corpo).map_err(|erro| ErroDeRecebimento::CorpoInvalido(erro.to_string()))
    }

    pub fn corpo(&self) -> &'a [u8] {
        self.corpo
    }
}

static CHAVES_CONHECIDAS: LazyLock<RwLock<HashMap<String, [u8; 32]>>> = LazyLock::new(Default::default);

static ULTIMA_BUSCA: LazyLock<Mutex<Option<Instant>>> = LazyLock::new(Default::default);

fn cliente_http() -> &'static Client {
    static CLIENTE: OnceLock<Client> = OnceLock::new();
    CLIENTE.get_or_init(|| {
        Client::builder()
            .user_agent(concat!("termo_webhook/", env!("CARGO_PKG_VERSION")))
            .timeout(Duration::from_secs(TEMPO_LIMITE_EM_SEGUNDOS))
            .redirect(Policy::none())
            .build()
            .expect("falha ao montar o cliente HTTP do termo_webhook")
    })
}

fn chave_em_cache(kid: &str) -> Option<[u8; 32]> {
    CHAVES_CONHECIDAS
        .read()
        .ok()
        .and_then(|chaves| chaves.get(kid).copied())
}

async fn buscar_chaves(configuracao: &ConfiguracaoDeRecebimento) -> Result<HashMap<String, [u8; 32]>, String> {
    let resposta = cliente_http()
        .get(configuracao.endereco_das_chaves())
        .send()
        .await
        .map_err(|erro| erro.to_string())?;

    if !resposta.status().is_success() {
        return Err(format!("hub respondeu {}", resposta.status()));
    }

    let corpo = resposta.bytes().await.map_err(|erro| erro.to_string())?;
    let conjunto: ConjuntoDeChaves = serde_json::from_slice(&corpo).map_err(|erro| erro.to_string())?;

    Ok(conjunto
        .keys
        .into_iter()
        .filter_map(|chave| {
            let bytes: [u8; 32] = URL_SAFE_NO_PAD.decode(chave.x).ok()?.try_into().ok()?;
            Some((chave.kid, bytes))
        })
        .collect())
}

// Um kid desconhecido busca as chaves de novo (o hub pode ter trocado a dele), mas no máximo
// a cada 30 s: entrega forjada com kid inventado não vira enxurrada de chamadas ao hub.
async fn chave_publica(configuracao: &ConfiguracaoDeRecebimento, kid: &str) -> Result<[u8; 32], ErroDeRecebimento> {
    if let Some(chave) = chave_em_cache(kid) {
        return Ok(chave);
    }

    let mut ultima_busca = ULTIMA_BUSCA.lock().await;

    if let Some(chave) = chave_em_cache(kid) {
        return Ok(chave);
    }

    if ultima_busca.is_some_and(|instante| instante.elapsed() < INTERVALO_MINIMO_ENTRE_BUSCAS) {
        return Err(ErroDeRecebimento::ChaveDesconhecida(kid.to_string()));
    }

    let chaves = buscar_chaves(configuracao)
        .await
        .map_err(ErroDeRecebimento::ChavesIndisponiveis)?;
    *ultima_busca = Some(Instant::now());

    let encontrada = chaves.get(kid).copied();
    if let Ok(mut conhecidas) = CHAVES_CONHECIDAS.write() {
        *conhecidas = chaves;
    }

    encontrada.ok_or_else(|| ErroDeRecebimento::ChaveDesconhecida(kid.to_string()))
}

fn cabecalho<'a>(cabecalhos: &'a HeaderMap, nome: &str) -> Option<&'a str> {
    cabecalhos.get(nome).and_then(|valor| valor.to_str().ok())
}

pub async fn conferir_entrega_recebida_do_hub_com_configuracao<'a>(
    configuracao: &ConfiguracaoDeRecebimento,
    cabecalhos: &HeaderMap,
    corpo: &'a [u8],
) -> Result<Entrega<'a>, ErroDeRecebimento> {
    let data = cabecalho(cabecalhos, CABECALHO_DATA).and_then(|valor| valor.trim().parse::<i64>().ok());
    let (Some(data), Some(kid), Some(assinatura)) = (
        data,
        cabecalho(cabecalhos, CABECALHO_CHAVE),
        cabecalho(cabecalhos, CABECALHO_ASSINATURA),
    ) else {
        return Err(ErroDeRecebimento::SemAssinatura);
    };

    if !data_dentro_da_janela(data) {
        return Err(ErroDeRecebimento::ForaDaJanela);
    }

    let chave = chave_publica(configuracao, kid.trim()).await?;

    if !assinatura_da_entrega_confere(&chave, data, &configuracao.aplicativo_id, corpo, assinatura) {
        return Err(ErroDeRecebimento::AssinaturaInvalida);
    }

    let identificacao: Identificacao =
        serde_json::from_slice(corpo).map_err(|erro| ErroDeRecebimento::CorpoInvalido(erro.to_string()))?;

    Ok(Entrega {
        corpo,
        id: identificacao.id,
        tipo: identificacao.tipo,
        versao: identificacao.versao,
    })
}

pub async fn conferir_entrega_recebida_do_hub<'a>(cabecalhos: &HeaderMap, corpo: &'a [u8]) -> Result<Entrega<'a>, ErroDeRecebimento> {
    let configuracao = ConfiguracaoDeRecebimento::carregar_do_ambiente_atual().await?;
    conferir_entrega_recebida_do_hub_com_configuracao(&configuracao, cabecalhos, corpo).await
}

pub async fn receber_evento_conferido_do_hub<T: Evento>(cabecalhos: &HeaderMap, corpo: &[u8]) -> Result<EventoRecebido<T>, ErroDeRecebimento> {
    conferir_entrega_recebida_do_hub(cabecalhos, corpo).await?.ler::<T>()
}

#[cfg(test)]
mod testes {
    use ed25519_dalek::{Signer, SigningKey};

    use super::*;
    use crate::webhook::assinatura::mensagem_da_entrega;

    fn assinar(chave: &SigningKey, data: i64, destino: &str, corpo: &[u8]) -> String {
        let assinatura = chave.sign(&mensagem_da_entrega(data, destino, corpo));
        format!("ed25519={}", URL_SAFE_NO_PAD.encode(assinatura.to_bytes()))
    }

    #[test]
    fn confere_so_a_entrega_do_proprio_destino_e_do_corpo_assinado() {
        let chave = SigningKey::from_bytes(&[7u8; 32]);
        let publica = chave.verifying_key().to_bytes();
        let destino = "spark-sell";
        let outro_destino = "termo-mcp";
        let data = chrono::Utc::now().timestamp();
        let corpo = br#"{"id":"01a109af-0000-7000-8000-000000000001","tipo":"t","versao":1}"#;
        let assinatura = assinar(&chave, data, destino, corpo);

        assert!(assinatura_da_entrega_confere(&publica, data, destino, corpo, &assinatura));
        assert!(!assinatura_da_entrega_confere(&publica, data, outro_destino, corpo, &assinatura));
        assert!(!assinatura_da_entrega_confere(&publica, data + 1, destino, corpo, &assinatura));
        assert!(!assinatura_da_entrega_confere(&publica, data, destino, b"{}", &assinatura));
        assert!(!assinatura_da_entrega_confere(&publica, data, destino, corpo, "ed25519=AAAA"));
    }

    #[tokio::test]
    async fn recusa_entrega_sem_cabecalhos_e_fora_da_janela() {
        let configuracao = ConfiguracaoDeRecebimento::nova("http://127.0.0.1:9", "spark-sell");
        let corpo = b"{}";

        let sem_cabecalhos = conferir_entrega_recebida_do_hub_com_configuracao(&configuracao, &HeaderMap::new(), corpo).await;
        assert_eq!(sem_cabecalhos.unwrap_err(), ErroDeRecebimento::SemAssinatura);

        let mut velha = HeaderMap::new();
        velha.insert(CABECALHO_DATA, (chrono::Utc::now().timestamp() - 900).into());
        velha.insert(CABECALHO_CHAVE, "kid".parse().unwrap());
        velha.insert(CABECALHO_ASSINATURA, "ed25519=AAAA".parse().unwrap());
        let fora_da_janela = conferir_entrega_recebida_do_hub_com_configuracao(&configuracao, &velha, corpo).await;
        assert_eq!(fora_da_janela.unwrap_err(), ErroDeRecebimento::ForaDaJanela);
    }
}