hostbat 0.9.0

Generic deterministic module host: mount content-identified modules over a syncbat Core.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

//! Content identity: the canonical-hash primitive plus the two digest newtypes
//! the host uses to name modules and whole compositions.
//!
//! Both digests are computed the same family-canonical way bvisor seals its plan
//! material: serialize a domain-separated view with batpak's canonical encoder,
//! then BLAKE3 it. Identical canonical inputs ⇒ identical digest; any change to
//! the declared bytes changes the digest.

use serde::Serialize;

use crate::error::HostError;

/// A 32-byte BLAKE3 digest over canonical bytes.
pub type Digest = [u8; 32];

/// Hash a domain-separated, canonically encoded view into a 32-byte digest.
///
/// # Errors
/// [`HostError::CanonicalEncoding`] if the canonical encoder rejects `value`
/// (unreachable for the crate's frozen wire shapes).
pub(crate) fn canonical_digest<T: Serialize>(value: &T) -> Result<Digest, HostError> {
    let bytes =
        batpak::canonical::to_bytes(value).map_err(|error| HostError::CanonicalEncoding {
            detail: error.to_string(),
        })?;
    Ok(batpak::event::hash::compute_hash(&bytes))
}

/// Render a 32-byte digest as lowercase hex.
fn hex(digest: &Digest) -> String {
    let mut out = String::with_capacity(64);
    for byte in digest {
        // Each byte renders as exactly two lowercase hex nibbles.
        out.push(char::from_digit(u32::from(byte >> 4), 16).unwrap_or('0'));
        out.push(char::from_digit(u32::from(byte & 0x0f), 16).unwrap_or('0'));
    }
    out
}

/// Content identity of a single mounted module: `H_module = H(canonical
/// manifest)` (see [`crate::manifest::HostModuleManifest`]).
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ModuleDigest(pub Digest);

impl ModuleDigest {
    /// The raw 32 bytes.
    #[must_use]
    pub const fn bytes(&self) -> &Digest {
        &self.0
    }

    /// Lowercase-hex rendering of the digest.
    #[must_use]
    pub fn to_hex(&self) -> String {
        hex(&self.0)
    }
}

impl std::fmt::Display for ModuleDigest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.to_hex())
    }
}

/// Content identity of a whole host composition: `H_host = H("hostbat.host.v1" ‖
/// canonical(sorted (module-id, module-digest) pairs))`. Mount order does not
/// affect it; the mounted module *set* does.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct HostFingerprint(pub Digest);

impl HostFingerprint {
    /// The raw 32 bytes.
    #[must_use]
    pub const fn bytes(&self) -> &Digest {
        &self.0
    }

    /// Lowercase-hex rendering of the fingerprint.
    #[must_use]
    pub fn to_hex(&self) -> String {
        hex(&self.0)
    }
}

impl std::fmt::Display for HostFingerprint {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.to_hex())
    }
}

/// Client-visible interface identity of a whole host composition:
/// `H_interface = H("hostbat.interface.v1" ‖ canonical(client-visible surface))`.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct InterfaceFingerprint(pub Digest);

impl InterfaceFingerprint {
    /// The raw 32 bytes.
    #[must_use]
    pub const fn bytes(&self) -> &Digest {
        &self.0
    }

    /// Lowercase-hex rendering of the fingerprint.
    #[must_use]
    pub fn to_hex(&self) -> String {
        hex(&self.0)
    }
}

impl std::fmt::Display for InterfaceFingerprint {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.to_hex())
    }
}