treeship_core/merkle/
checkpoint.rs

1use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
2use ed25519_dalek::{Signature, Verifier, VerifyingKey};
3use serde::{Deserialize, Serialize};
4
5use crate::attestation::{Signer, SignerError};
6use crate::statements::unix_to_rfc3339;
7
8use super::tree::MerkleTree;
9
10/// A signed snapshot of the Merkle tree at a point in time.
11#[derive(Debug, Clone, Serialize, Deserialize)]
12pub struct Checkpoint {
13    pub index: u64,
14    /// Root hash in `sha256:<hex>` format.
15    pub root: String,
16    pub tree_size: usize,
17    pub height: usize,
18    /// RFC 3339 timestamp.
19    pub signed_at: String,
20    /// Key ID of the signer.
21    pub signer: String,
22    /// Base64url-encoded public key bytes.
23    pub public_key: String,
24    /// Base64url-encoded Ed25519 signature of the canonical form.
25    pub signature: String,
26    /// Merkle algorithm used. Missing = v1 (sha256-duplicate-last).
27    #[serde(default, skip_serializing_if = "Option::is_none")]
28    pub algorithm: Option<String>,
29}
30
31/// Errors from checkpoint creation.
32#[derive(Debug)]
33pub enum CheckpointError {
34    EmptyTree,
35    Signing(SignerError),
36}
37
38impl std::fmt::Display for CheckpointError {
39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
40        match self {
41            Self::EmptyTree => write!(f, "cannot checkpoint an empty tree"),
42            Self::Signing(e) => write!(f, "checkpoint signing failed: {}", e),
43        }
44    }
45}
46
47impl std::error::Error for CheckpointError {}
48impl From<SignerError> for CheckpointError {
49    fn from(e: SignerError) -> Self {
50        Self::Signing(e)
51    }
52}
53
54impl Checkpoint {
55    /// Create a signed checkpoint from the current tree state.
56    ///
57    /// The canonical form for signing is: `{root}|{tree_size}|{signed_at}`
58    pub fn create(
59        index: u64,
60        tree: &MerkleTree,
61        signer: &dyn Signer,
62    ) -> Result<Self, CheckpointError> {
63        let root_bytes = tree.root().ok_or(CheckpointError::EmptyTree)?;
64        let root = format!("sha256:{}", hex::encode(root_bytes));
65
66        let secs = std::time::SystemTime::now()
67            .duration_since(std::time::UNIX_EPOCH)
68            .unwrap_or_default()
69            .as_secs();
70        let signed_at = unix_to_rfc3339(secs);
71
72        let canonical = format!("{}|{}|{}|{}|{}|{}", index, root, tree.len(), tree.height(), signer.key_id(), signed_at);
73        let sig_bytes = signer.sign(canonical.as_bytes())?;
74        let signature = URL_SAFE_NO_PAD.encode(&sig_bytes);
75        let public_key = URL_SAFE_NO_PAD.encode(signer.public_key_bytes());
76
77        Ok(Self {
78            index,
79            root,
80            tree_size: tree.len(),
81            height: tree.height(),
82            signed_at,
83            signer: signer.key_id().to_string(),
84            public_key,
85            signature,
86            algorithm: Some(super::tree::MERKLE_ALGORITHM_V2.to_string()),
87        })
88    }
89
90    /// Verify the checkpoint signature. Returns `false` on any failure
91    /// (bad encoding, wrong key size, invalid signature). Never panics.
92    pub fn verify(&self) -> bool {
93        let pub_bytes = match URL_SAFE_NO_PAD.decode(&self.public_key) {
94            Ok(b) => b,
95            Err(_) => return false,
96        };
97        let pub_array: [u8; 32] = match pub_bytes.as_slice().try_into() {
98            Ok(a) => a,
99            Err(_) => return false,
100        };
101        let vk = match VerifyingKey::from_bytes(&pub_array) {
102            Ok(k) => k,
103            Err(_) => return false,
104        };
105
106        let canonical = format!("{}|{}|{}|{}|{}|{}", self.index, self.root, self.tree_size, self.height, self.signer, self.signed_at);
107
108        let sig_bytes = match URL_SAFE_NO_PAD.decode(&self.signature) {
109            Ok(b) => b,
110            Err(_) => return false,
111        };
112        let sig_array: [u8; 64] = match sig_bytes.as_slice().try_into() {
113            Ok(a) => a,
114            Err(_) => return false,
115        };
116        let sig = Signature::from_bytes(&sig_array);
117
118        vk.verify(canonical.as_bytes(), &sig).is_ok()
119    }
120}
treeship_core/merkle/checkpoint.rs

treeship_core/merkle/
checkpoint.rs
