vc-shared 0.1.0

Canonical JSON, SHA256 hashing, and Merkle root utilities for Visual Compiler
Documentation
//! Hashing utilities using SHA256.

use serde::{Deserialize, Deserializer, Serialize, Serializer};
use sha2::{Digest, Sha256};
use std::fmt;
use std::str::FromStr;
use thiserror::Error;

/// A SHA256 digest (32 bytes).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Sha256Digest([u8; 32]);

/// Serialization helpers for `Sha256Digest` as hex string.
mod hex_serde {
    use super::*;

    pub fn serialize<S>(bytes: &[u8; 32], serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        let hex = hex::encode(bytes);
        serializer.serialize_str(&hex)
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<[u8; 32], D::Error>
    where
        D: Deserializer<'de>,
    {
        let s = String::deserialize(deserializer)?;
        let bytes = hex::decode(s).map_err(serde::de::Error::custom)?;
        bytes.try_into().map_err(|_| serde::de::Error::custom("expected 32 bytes"))
    }
}

impl Serialize for Sha256Digest {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        hex_serde::serialize(&self.0, serializer)
    }
}

impl<'de> Deserialize<'de> for Sha256Digest {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let bytes = hex_serde::deserialize(deserializer)?;
        Ok(Sha256Digest(bytes))
    }
}

impl Sha256Digest {
    #[must_use]
    pub fn to_hex(&self) -> String {
        hex::encode(self.0)
    }

    #[must_use]
    pub fn as_bytes(&self) -> &[u8; 32] {
        &self.0
    }
}

impl AsRef<[u8]> for Sha256Digest {
    fn as_ref(&self) -> &[u8] {
        &self.0
    }
}

impl From<[u8; 32]> for Sha256Digest {
    fn from(bytes: [u8; 32]) -> Self {
        Sha256Digest(bytes)
    }
}

impl From<Sha256Digest> for [u8; 32] {
    fn from(digest: Sha256Digest) -> Self {
        digest.0
    }
}

impl fmt::Display for Sha256Digest {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_hex())
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum ParseDigestError {
    #[error("expected exactly 64 hexadecimal characters, got {0}")]
    InvalidLength(usize),
    #[error("invalid hexadecimal character")]
    InvalidHex,
}

impl FromStr for Sha256Digest {
    type Err = ParseDigestError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let trimmed = s.trim();
        if trimmed.len() != 64 {
            return Err(ParseDigestError::InvalidLength(trimmed.len()));
        }
        let mut bytes = [0u8; 32];
        for (i, chunk) in trimmed.as_bytes().chunks(2).enumerate() {
            let byte = u8::from_str_radix(
                std::str::from_utf8(chunk).map_err(|_| ParseDigestError::InvalidHex)?,
                16,
            )
            .map_err(|_| ParseDigestError::InvalidHex)?;
            bytes[i] = byte;
        }
        Ok(Sha256Digest(bytes))
    }
}

/// Computes the SHA256 digest of the given bytes.
#[must_use]
pub fn sha256(data: &[u8]) -> Sha256Digest {
    let mut hasher = Sha256::new();
    hasher.update(data);
    Sha256Digest(hasher.finalize().into())
}

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

    #[test]
    fn sha256_empty() {
        let digest = sha256(b"");
        assert_eq!(
            digest.to_hex(),
            "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        );
    }

    #[test]
    fn sha256_abc() {
        let digest = sha256(b"abc");
        assert_eq!(
            digest.to_hex(),
            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
        );
    }

    #[test]
    fn sha256_quick_brown_fox() {
        let data = b"The quick brown fox jumps over the lazy dog";
        let digest = sha256(data);
        assert_eq!(
            digest.to_hex(),
            "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592"
        );
    }

    #[test]
    fn sha256_quick_brown_fox_with_dot() {
        let data = b"The quick brown fox jumps over the lazy dog.";
        let digest = sha256(data);
        assert_eq!(
            digest.to_hex(),
            "ef537f25c895bfa782526529a9b63d97aa631564d5d789c2b765448c8635fb6c"
        );
    }

    #[test]
    fn sha256_deterministic() {
        let data = b"hello";
        let d1 = sha256(data);
        let d2 = sha256(data);
        assert_eq!(d1, d2);
    }

    #[test]
    fn parse_valid_digest() {
        let hex = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
        let digest: Sha256Digest = hex.parse().unwrap();
        assert_eq!(digest.to_hex(), hex);
    }

    #[test]
    fn parse_invalid_length() {
        let result = "e3b0c4".parse::<Sha256Digest>();
        assert!(matches!(result, Err(ParseDigestError::InvalidLength(6))));
    }

    #[test]
    fn parse_invalid_hex() {
        let result = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b85g"
            .parse::<Sha256Digest>();
        assert!(matches!(result, Err(ParseDigestError::InvalidHex)));
    }

    #[test]
    fn from_str_roundtrip() {
        let data = b"hello";
        let digest = sha256(data);
        let hex = digest.to_hex();
        let parsed: Sha256Digest = hex.parse().unwrap();
        assert_eq!(digest, parsed);
    }
}