kestrove-core/crates/kv-sync/src/transport.rs

//! HTTPS transport: rustls, TLS 1.3 only, SPKI pinning (docs/02 "Transport").
//!
//! A pin is the base64 SHA-256 of a certificate's DER `SubjectPublicKeyInfo` (the HPKP
//! `pin-sha256` format). Normal WebPKI chain validation always runs first; on top of that, at
//! least one certificate the server presents (leaf or intermediate) must match a pin; a root that the
//! server does not send cannot be pinned. Configure
//! a primary and a backup pin so a key rotation never locks the client out.
//!
//! Plain `http://` is accepted only for loopback hosts (local development and tests).
//!
//! On wasm32 (the web vault) reqwest sends through the browser's `fetch`: the browser does TLS and the
//! page is served from the same origin as the API, so pinning and the rustls config are native only.

#[cfg(not(target_arch = "wasm32"))]
use std::sync::Arc;

use base64::{
    engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD},
    Engine,
};
#[cfg(not(target_arch = "wasm32"))]
use rustls::{
    client::{
        danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier},
        WebPkiServerVerifier,
    },
    pki_types::{CertificateDer, ServerName, UnixTime},
    CertificateError, DigitallySignedStruct, OtherError, RootCertStore, SignatureScheme,
};
#[cfg(not(target_arch = "wasm32"))]
use sha2::{Digest, Sha256};

use crate::{ServerConfig, SyncError};

/// Raised inside the TLS handshake when no certificate matches a pin.
#[derive(Debug)]
pub struct PinMismatch;

impl std::fmt::Display for PinMismatch {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("server certificate does not match any pinned SPKI hash")
    }
}

impl std::error::Error for PinMismatch {}

/// Decodes `sha256/…`, standard or URL-safe base64 pins.
pub fn parse_pin(pin: &str) -> Result<[u8; 32], SyncError> {
    let p = pin.trim().trim_start_matches("sha256/");
    let raw = STANDARD
        .decode(p)
        .or_else(|_| URL_SAFE_NO_PAD.decode(p.trim_end_matches('=')))
        .map_err(|_| SyncError::Config(format!("pin is not base64: {pin}")))?;
    raw.try_into().map_err(|_| SyncError::Config(format!("pin is not a SHA-256 hash: {pin}")))
}

#[cfg(not(target_arch = "wasm32"))]
/// `base64(SHA-256(SPKI))` of a DER certificate. Useful for tooling and tests.
pub fn spki_pin_of(cert_der: &[u8]) -> Result<String, SyncError> {
    Ok(STANDARD.encode(spki_hash(&CertificateDer::from(cert_der))?))
}

#[cfg(not(target_arch = "wasm32"))]
fn spki_hash(cert: &CertificateDer<'_>) -> Result<[u8; 32], SyncError> {
    let parsed = webpki::EndEntityCert::try_from(cert).map_err(|e| SyncError::Config(format!("certificate: {e}")))?;
    Ok(Sha256::digest(parsed.subject_public_key_info().as_ref()).into())
}

#[cfg(not(target_arch = "wasm32"))]
#[derive(Debug)]
struct PinningVerifier {
    inner: Arc<WebPkiServerVerifier>,
    pins: Vec<[u8; 32]>,
}

#[cfg(not(target_arch = "wasm32"))]
impl ServerCertVerifier for PinningVerifier {
    fn verify_server_cert(
        &self,
        end_entity: &CertificateDer<'_>,
        intermediates: &[CertificateDer<'_>],
        server_name: &ServerName<'_>,
        ocsp_response: &[u8],
        now: UnixTime,
    ) -> Result<ServerCertVerified, rustls::Error> {
        let verified = self.inner.verify_server_cert(end_entity, intermediates, server_name, ocsp_response, now)?;
        if self.pins.is_empty() {
            return Ok(verified);
        }
        let matched = std::iter::once(end_entity)
            .chain(intermediates)
            .filter_map(|c| spki_hash(c).ok())
            .any(|h| self.pins.contains(&h));
        if matched {
            Ok(verified)
        } else {
            Err(rustls::Error::InvalidCertificate(CertificateError::Other(OtherError(Arc::new(PinMismatch)))))
        }
    }

    fn verify_tls12_signature(
        &self,
        _message: &[u8],
        _cert: &CertificateDer<'_>,
        _dss: &DigitallySignedStruct,
    ) -> Result<HandshakeSignatureValid, rustls::Error> {
        // Unreachable: the config only enables TLS 1.3.
        Err(rustls::Error::PeerIncompatible(rustls::PeerIncompatible::Tls12NotOffered))
    }

    fn verify_tls13_signature(
        &self,
        message: &[u8],
        cert: &CertificateDer<'_>,
        dss: &DigitallySignedStruct,
    ) -> Result<HandshakeSignatureValid, rustls::Error> {
        self.inner.verify_tls13_signature(message, cert, dss)
    }

    fn supported_verify_schemes(&self) -> Vec<SignatureScheme> {
        self.inner.supported_verify_schemes()
    }
}

#[cfg(not(target_arch = "wasm32"))]
/// Builds the rustls config: TLS 1.3 only, ring provider, Mozilla roots plus `extra_roots`, pin check.
pub fn tls_config(pins: &[String], extra_roots: &[Vec<u8>]) -> Result<rustls::ClientConfig, SyncError> {
    let pins = pins.iter().map(|p| parse_pin(p)).collect::<Result<Vec<_>, _>>()?;
    let provider = Arc::new(rustls::crypto::ring::default_provider());
    let mut roots = RootCertStore { roots: webpki_roots::TLS_SERVER_ROOTS.to_vec() };
    for der in extra_roots {
        roots.add(CertificateDer::from(der.clone())).map_err(|e| SyncError::Config(format!("root: {e}")))?;
    }
    let inner = WebPkiServerVerifier::builder_with_provider(Arc::new(roots), provider.clone())
        .build()
        .map_err(|e| SyncError::Config(e.to_string()))?;
    let mut cfg = rustls::ClientConfig::builder_with_provider(provider)
        .with_protocol_versions(&[&rustls::version::TLS13])
        .map_err(|e| SyncError::Config(e.to_string()))?
        .dangerous()
        .with_custom_certificate_verifier(Arc::new(PinningVerifier { inner, pins }))
        .with_no_client_auth();
    cfg.alpn_protocols = vec![b"h2".to_vec(), b"http/1.1".to_vec()];
    Ok(cfg)
}

fn is_loopback(url: &reqwest::Url) -> bool {
    match url.host() {
        Some(url::Host::Domain(d)) => d == "localhost" || d.ends_with(".localhost"),
        Some(url::Host::Ipv4(ip)) => ip.is_loopback(),
        Some(url::Host::Ipv6(ip)) => ip.is_loopback(),
        None => false,
    }
}

/// Validates the base URL (https, or http on loopback) and normalizes it to end without a slash.
pub fn normalize_base_url(raw: &str) -> Result<String, SyncError> {
    let url = reqwest::Url::parse(raw.trim()).map_err(|e| SyncError::Config(format!("server URL: {e}")))?;
    match url.scheme() {
        "https" => {}
        "http" if is_loopback(&url) => {}
        _ => return Err(SyncError::Config("server URL must use https".into())),
    }
    if url.query().is_some() || url.fragment().is_some() {
        return Err(SyncError::Config("server URL must not have a query or fragment".into()));
    }
    Ok(url.as_str().trim_end_matches('/').to_string())
}

#[cfg(not(target_arch = "wasm32"))]
pub fn http_client(cfg: &ServerConfig) -> Result<reqwest::Client, SyncError> {
    reqwest::Client::builder()
        .use_preconfigured_tls(tls_config(&cfg.spki_pins, &cfg.extra_roots_der)?)
        .https_only(false) // enforced by normalize_base_url (http only on loopback)
        .connect_timeout(std::time::Duration::from_secs(15))
        .timeout(std::time::Duration::from_secs(60))
        .user_agent(concat!("kestrove-core/", env!("CARGO_PKG_VERSION")))
        .build()
        .map_err(|e| SyncError::Config(e.to_string()))
}

/// Browser `fetch`: TLS, timeouts and certificate checks belong to the browser. Pins are ignored.
#[cfg(target_arch = "wasm32")]
pub fn http_client(_cfg: &ServerConfig) -> Result<reqwest::Client, SyncError> {
    reqwest::Client::builder().build().map_err(|e| SyncError::Config(e.to_string()))
}

#[cfg(target_arch = "wasm32")]
pub(crate) fn classify(e: reqwest::Error) -> SyncError {
    SyncError::Network(e.to_string())
}

#[cfg(not(target_arch = "wasm32"))]
/// Maps a reqwest error to `PinMismatch` when the handshake failed on our pin check.
pub(crate) fn classify(e: reqwest::Error) -> SyncError {
    let mut src: Option<&(dyn std::error::Error + 'static)> = Some(&e);
    while let Some(err) = src {
        if err.downcast_ref::<PinMismatch>().is_some() {
            return SyncError::PinMismatch;
        }
        // `io::Error::source()` skips the wrapped error itself, so look inside explicitly.
        let tls = err
            .downcast_ref::<rustls::Error>()
            .or_else(|| err.downcast_ref::<std::io::Error>().and_then(|io| io.get_ref()?.downcast_ref()));
        if let Some(rustls::Error::InvalidCertificate(CertificateError::Other(o))) = tls {
            if o.0.downcast_ref::<PinMismatch>().is_some() {
                return SyncError::PinMismatch;
            }
        }
        src = err.source();
    }
    if format!("{e:?}").contains("PinMismatch") {
        return SyncError::PinMismatch;
    }
    SyncError::Network(e.to_string())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn base_url_rules() {
        assert_eq!(normalize_base_url("https://vault.example.com/").unwrap(), "https://vault.example.com");
        assert_eq!(normalize_base_url("http://127.0.0.1:8080").unwrap(), "http://127.0.0.1:8080");
        assert!(normalize_base_url("http://localhost:3000").is_ok());
        assert!(normalize_base_url("http://vault.example.com").is_err());
        assert!(normalize_base_url("ftp://x").is_err());
    }

    #[test]
    fn pin_formats() {
        let raw = [7u8; 32];
        assert_eq!(parse_pin(&STANDARD.encode(raw)).unwrap(), raw);
        assert_eq!(parse_pin(&format!("sha256/{}", STANDARD.encode(raw))).unwrap(), raw);
        assert_eq!(parse_pin(&URL_SAFE_NO_PAD.encode(raw)).unwrap(), raw);
        assert!(parse_pin("AAAA").is_err());
        assert!(tls_config(&["nope!".into()], &[]).is_err());
    }
}