OXYGENHUB
# 7b9809e67c3d oxygen / crates / oxy-core / src / hash.rs
4.3 KiB · Rust · last changed Import the Oxygen specification and the first Rust implementation (root change) 1 month ago source blame history raw
1 
//! Object references: BLAKE3-256 over a domain-separating header and the body
2 
//! (spec §5.2).
3
4 
use std::fmt;
5
6 
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
7 
pub struct ObjectRef(pub [u8; 32]);
8
9 
/// A change is referenced by the ObjectRef of its encoding.
10 
pub type ChangeHash = ObjectRef;
11 
/// An identity is referenced by the ObjectRef of its encoding.
12 
pub type KeyId = ObjectRef;
13
14 
impl ObjectRef {
15 
    /// Reserved: means "this change" inside a change (spec §5.2, §7.4).
16 
    pub const ZERO: ObjectRef = ObjectRef([0; 32]);
17
18 
    pub fn is_zero(&self) -> bool {
19 
        *self == Self::ZERO
20 
    }
21 
    pub fn to_hex(&self) -> String {
22 
        hex::encode(self.0)
23 
    }
24 
    pub fn from_hex(s: &str) -> Option<ObjectRef> {
25 
        let v = hex::decode(s).ok()?;
26 
        let a: [u8; 32] = v.try_into().ok()?;
27 
        Some(ObjectRef(a))
28 
    }
29 
    pub fn from_slice(b: &[u8]) -> Option<ObjectRef> {
30 
        let a: [u8; 32] = b.try_into().ok()?;
31 
        Some(ObjectRef(a))
32 
    }
33 
    /// First `n` hex characters.
34 
    pub fn short(&self, n: usize) -> String {
35 
        let h = self.to_hex();
36 
        h[..n.min(h.len())].to_string()
37 
    }
38 
    pub fn starts_with_hex(&self, prefix: &str) -> bool {
39 
        self.to_hex().starts_with(prefix)
40 
    }
41 
}
42
43 
impl fmt::Display for ObjectRef {
44 
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
45 
        f.write_str(&self.to_hex())
46 
    }
47 
}
48
49 
impl fmt::Debug for ObjectRef {
50 
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51 
        write!(f, "#{}", self.short(12))
52 
    }
53 
}
54
55 
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
56 
pub enum ObjectType {
57 
    Chunk,
58 
    Blob,
59 
    Change,
60 
    Checkpoint,
61 
    Op,
62 
    Attest,
63 
    Identity,
64 
    Policy,
65 
    State,
66 
}
67
68 
impl ObjectType {
69 
    pub const ALL: [ObjectType; 9] = [
70 
        ObjectType::Chunk,
71 
        ObjectType::Blob,
72 
        ObjectType::Change,
73 
        ObjectType::Checkpoint,
74 
        ObjectType::Op,
75 
        ObjectType::Attest,
76 
        ObjectType::Identity,
77 
        ObjectType::Policy,
78 
        ObjectType::State,
79 
    ];
80
81 
    pub fn name(self) -> &'static str {
82 
        match self {
83 
            ObjectType::Chunk => "chunk",
84 
            ObjectType::Blob => "blob",
85 
            ObjectType::Change => "change",
86 
            ObjectType::Checkpoint => "checkpoint",
87 
            ObjectType::Op => "op",
88 
            ObjectType::Attest => "attest",
89 
            ObjectType::Identity => "identity",
90 
            ObjectType::Policy => "policy",
91 
            ObjectType::State => "state",
92 
        }
93 
    }
94
95 
    pub fn from_name(s: &str) -> Option<ObjectType> {
96 
        Self::ALL.iter().copied().find(|t| t.name() == s)
97 
    }
98 
}
99
100 
/// `ObjectRef = BLAKE3-256("oxy1 " || type || " " || decimal(len) || 0x00 || body)`.
101 
pub fn hash_object(ty: ObjectType, body: &[u8]) -> ObjectRef {
102 
    let mut h = blake3::Hasher::new();
103 
    h.update(&header(ty, body.len()));
104 
    h.update(body);
105 
    ObjectRef(*h.finalize().as_bytes())
106 
}
107
108 
pub fn header(ty: ObjectType, len: usize) -> Vec<u8> {
109 
    let mut v = Vec::with_capacity(32);
110 
    v.extend_from_slice(b"oxy1 ");
111 
    v.extend_from_slice(ty.name().as_bytes());
112 
    v.push(b' ');
113 
    v.extend_from_slice(len.to_string().as_bytes());
114 
    v.push(0);
115 
    v
116 
}
117
118 
#[cfg(test)]
119 
mod tests {
120 
    use super::*;
121
122 
    #[test]
123 
    fn header_matches_spec() {
124 
        assert_eq!(header(ObjectType::Chunk, 5), b"oxy1 chunk 5\0");
125 
        assert_eq!(header(ObjectType::Change, 1234), b"oxy1 change 1234\0");
126 
    }
127
128 
    #[test]
129 
    fn types_are_domain_separated() {
130 
        let body = b"same bytes";
131 
        let a = hash_object(ObjectType::Chunk, body);
132 
        let b = hash_object(ObjectType::Blob, body);
133 
        assert_ne!(a, b);
134 
        assert_eq!(a, hash_object(ObjectType::Chunk, body));
135 
        // Reference vector: pin so the format cannot drift silently.
136 
        assert_eq!(
137 
            hash_object(ObjectType::Chunk, b"").to_hex(),
138 
            blake3::hash(b"oxy1 chunk 0\0").to_hex().as_str()
139 
        );
140 
    }
141
142 
    #[test]
143 
    fn hex_round_trip() {
144 
        let r = hash_object(ObjectType::Chunk, b"x");
145 
        assert_eq!(ObjectRef::from_hex(&r.to_hex()), Some(r));
146 
        assert_eq!(ObjectRef::from_hex("zz"), None);
147 
        assert!(r.starts_with_hex(&r.short(7)));
148 
        assert!(ObjectRef::ZERO.is_zero());
149 
        for t in ObjectType::ALL {
150 
            assert_eq!(ObjectType::from_name(t.name()), Some(t));
151 
        }
152 
    }
153 
}