OXYGENHUB
◆ v0.4.5 oxygen / crates / oxy-core / src / hash.rs
4.6 KiB · Rust · last changed Grants let certified keys act for an author (keyless step 5a) 18 days ago source blame history raw
ff0af1ee unknown 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,
86e682c2 Andy McCall ↶ 65 
    State,
fc1a466a Andy McCall ↶ 66 
    Receipt,
02e69188 Andy McCall ↶ 67 
    /// A short-lived key's certificate (oxygenhub#241).
68 
    Certificate,
a2387d54 Andy McCall ↶ 69 
    /// An author's grant to a certified subject (§14.7).
70 
    Grant,
ff0af1ee unknown 71 
}
72
73 
impl ObjectType {
a2387d54 Andy McCall ↶ 74 
    pub const ALL: [ObjectType; 12] = [
ff0af1ee unknown 75 
        ObjectType::Chunk,
76 
        ObjectType::Blob,
77 
        ObjectType::Change,
78 
        ObjectType::Checkpoint,
79 
        ObjectType::Op,
80 
        ObjectType::Attest,
81 
        ObjectType::Identity,
82 
        ObjectType::Policy,
86e682c2 Andy McCall ↶ 83 
        ObjectType::State,
fc1a466a Andy McCall ↶ 84 
        ObjectType::Receipt,
02e69188 Andy McCall ↶ 85 
        ObjectType::Certificate,
a2387d54 Andy McCall ↶ 86 
        ObjectType::Grant,
ff0af1ee unknown 87 
    ];
88
89 
    pub fn name(self) -> &'static str {
90 
        match self {
91 
            ObjectType::Chunk => "chunk",
92 
            ObjectType::Blob => "blob",
93 
            ObjectType::Change => "change",
94 
            ObjectType::Checkpoint => "checkpoint",
95 
            ObjectType::Op => "op",
96 
            ObjectType::Attest => "attest",
97 
            ObjectType::Identity => "identity",
98 
            ObjectType::Policy => "policy",
86e682c2 Andy McCall ↶ 99 
            ObjectType::State => "state",
fc1a466a Andy McCall ↶ 100 
            ObjectType::Receipt => "receipt",
02e69188 Andy McCall ↶ 101 
            ObjectType::Certificate => "certificate",
a2387d54 Andy McCall ↶ 102 
            ObjectType::Grant => "grant",
ff0af1ee unknown 103 
        }
104 
    }
105
106 
    pub fn from_name(s: &str) -> Option<ObjectType> {
107 
        Self::ALL.iter().copied().find(|t| t.name() == s)
108 
    }
109 
}
110
111 
/// `ObjectRef = BLAKE3-256("oxy1 " || type || " " || decimal(len) || 0x00 || body)`.
112 
pub fn hash_object(ty: ObjectType, body: &[u8]) -> ObjectRef {
113 
    let mut h = blake3::Hasher::new();
114 
    h.update(&header(ty, body.len()));
115 
    h.update(body);
116 
    ObjectRef(*h.finalize().as_bytes())
117 
}
118
119 
pub fn header(ty: ObjectType, len: usize) -> Vec<u8> {
120 
    let mut v = Vec::with_capacity(32);
121 
    v.extend_from_slice(b"oxy1 ");
122 
    v.extend_from_slice(ty.name().as_bytes());
123 
    v.push(b' ');
124 
    v.extend_from_slice(len.to_string().as_bytes());
125 
    v.push(0);
126 
    v
127 
}
128
129 
#[cfg(test)]
130 
mod tests {
131 
    use super::*;
132
133 
    #[test]
134 
    fn header_matches_spec() {
135 
        assert_eq!(header(ObjectType::Chunk, 5), b"oxy1 chunk 5\0");
136 
        assert_eq!(header(ObjectType::Change, 1234), b"oxy1 change 1234\0");
137 
    }
138
139 
    #[test]
140 
    fn types_are_domain_separated() {
141 
        let body = b"same bytes";
142 
        let a = hash_object(ObjectType::Chunk, body);
143 
        let b = hash_object(ObjectType::Blob, body);
144 
        assert_ne!(a, b);
145 
        assert_eq!(a, hash_object(ObjectType::Chunk, body));
146 
        // Reference vector: pin so the format cannot drift silently.
147 
        assert_eq!(
148 
            hash_object(ObjectType::Chunk, b"").to_hex(),
149 
            blake3::hash(b"oxy1 chunk 0\0").to_hex().as_str()
150 
        );
151 
    }
152
153 
    #[test]
154 
    fn hex_round_trip() {
155 
        let r = hash_object(ObjectType::Chunk, b"x");
156 
        assert_eq!(ObjectRef::from_hex(&r.to_hex()), Some(r));
157 
        assert_eq!(ObjectRef::from_hex("zz"), None);
158 
        assert!(r.starts_with_hex(&r.short(7)));
159 
        assert!(ObjectRef::ZERO.is_zero());
160 
        for t in ObjectType::ALL {
161 
            assert_eq!(ObjectType::from_name(t.name()), Some(t));
162 
        }
163 
    }
164 
}