M1: persistent vault, local unlock key, sync client, test vectors

kv-store: SQLite (bundled) and in-memory Store holding only ciphertext envelopes, with base copies for three-way merges and a 10-version history. kv-ffi: VaultCore::open(path); persisted account record; local unlock key (enable/unlock_with_local_key/disable); async sync API (configure_server, set_device_signer, register_account, login, sync_now, logout, devices); DeviceSigner foreign trait; IntegrityAlarm/PinMismatch/... error variants. kv-sync: reqwest + rustls (TLS 1.3 only, ring) with SPKI pinning; OPAQUE client on kv-proto's OpaqueSuite; RFC 9421 signing per kv_proto::httpsig; pull/push with If-Match, field-level three-way merge, edit-beats-delete; signed manifest (canonical CBOR, Merkle root, prev chain, Ed25519) with rollback/fork/Merkle checks as hard integrity alarms. Tested against a wiremock fake server, plus an #[ignore] test against kestrove-server. kv-crypto: gen-vectors example and tests reproducing kestrove-spec/vectors. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-15 21:52:14 +09:00
parent cbef689903
commit 2be9a3baad
35 changed files with 6832 additions and 183 deletions
@@ -0,0 +1,216 @@
+//! 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).
+
+use std::sync::Arc;
+
+use base64::{
+    engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD},
+    Engine,
+};
+use rustls::{
+    client::{
+        danger::{HandshakeSignatureValid, ServerCertVerified, ServerCertVerifier},
+        WebPkiServerVerifier,
+    },
+    pki_types::{CertificateDer, ServerName, UnixTime},
+    CertificateError, DigitallySignedStruct, OtherError, RootCertStore, SignatureScheme,
+};
+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}")))
+}
+
+/// `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))?))
+}
+
+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())
+}
+
+#[derive(Debug)]
+struct PinningVerifier {
+    inner: Arc<WebPkiServerVerifier>,
+    pins: Vec<[u8; 32]>,
+}
+
+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()
+    }
+}
+
+/// 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())
+}
+
+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()))
+}
+
+/// 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());
+    }
+}