Skip to main content

hyprstream_core/storage/cas/
manifest.rs

1//! L1 blob manifest + multihash address helpers.
2//!
3//! The manifest is the substrate's ingest result: it carries the canonical
4//! self-describing content address (CIDv1 multihash), the legacy XET merkle hex
5//! (for the current wire and provenance keying), the reconstruction xorb set, the
6//! reconstructed byte length, and the `security_label` **carrier field** that
7//! unblocks #699 carrier-(b).
8
9use hyprstream_rpc::auth::mac::{ContentBoundLabel, LabeledObject, SecurityLabel};
10use hyprstream_rpc::cid::{decode_cid, encode_cid, Codec, HashAlgo};
11use serde::{Deserialize, Serialize};
12
13use super::CasError;
14
15/// Multicodec for a sealed labeled blob manifest.
16///
17/// The raw reconstruction shard remains keyed by its legacy merkle; the public
18/// CAS CID identifies the manifest that binds that shard to its label.
19pub const FILE_RECONSTRUCTION_CODEC: Codec = Codec::XetManifest;
20
21/// The L1 manifest describing one stored blob.
22///
23/// This is the sealed substrate-level result type. It supersedes
24/// `cas_serve::PutResult` for substrate callers by adding the canonical
25/// [`Self::cid`] and required [`Self::security_label`], while keeping
26/// [`Self::merkle`] and [`Self::xorb_hashes`] so existing wire/provenance
27/// behavior is preserved.
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29pub struct BlobManifest {
30    /// Canonical self-describing content address (CIDv1, base32 multibase). Encodes
31    /// the reconstruction codec + multihash algorithm + digest, so it is portable
32    /// across the local registry, federation, and XET CAS uniformly.
33    pub cid: String,
34
35    /// Legacy XET merkle root (hex). Identical to `cas_serve::PutResult::merkle`.
36    /// Retained because the current `putBlob`/`getBlob` wire and the provenance
37    /// store key on it.
38    pub merkle: String,
39
40    /// Reconstruction xorb set (hex xorb hashes), from the underlying store.
41    pub xorb_hashes: Vec<String>,
42
43    /// Bytes newly written after content-addressed dedup within the domain
44    /// (`0` if fully deduplicated).
45    pub bytes_stored: u64,
46
47    /// Total byte length of the reconstructed content.
48    pub byte_len: u64,
49
50    /// **Trusted content-bound label (#1270).** The MAC object label for this
51    /// sealed blob, derived from the
52    /// [`DedupDomain`](crate::storage::cas::DedupDomain) at seal time.
53    ///
54    /// The substrate derives this via [`crate::mac::cas_pep::seal_label`] as a
55    /// restrict-only join of the domain's structural label and any trusted
56    /// staging hint. It is required and covered by the manifest CID, so
57    /// relabeling necessarily creates a distinct object.
58    pub security_label: SecurityLabel,
59}
60
61/// The exact, canonical preimage addressed by a [`BlobManifest`] CID. `cid` is
62/// intentionally excluded to avoid self-reference. `bytes_stored` is an ingest
63/// receipt (dedup accounting), not content truth, so it is also excluded; all
64/// semantic object fields, including the required label, are covered.
65#[derive(Serialize)]
66struct ManifestPreimage<'a> {
67    merkle: &'a str,
68    xorb_hashes: &'a [String],
69    byte_len: u64,
70    security_label: SecurityLabel,
71}
72
73impl BlobManifest {
74    /// Construct a sealed, labeled manifest and derive its content-bound CID.
75    pub fn new(
76        merkle: String,
77        xorb_hashes: Vec<String>,
78        bytes_stored: u64,
79        byte_len: u64,
80        security_label: SecurityLabel,
81    ) -> Result<Self, CasError> {
82        let mut manifest = Self {
83            cid: String::new(),
84            merkle,
85            xorb_hashes,
86            bytes_stored,
87            byte_len,
88            security_label,
89        };
90        manifest.cid = manifest.recomputed_cid()?;
91        Ok(manifest)
92    }
93
94    fn preimage(&self) -> ManifestPreimage<'_> {
95        ManifestPreimage {
96            merkle: &self.merkle,
97            xorb_hashes: &self.xorb_hashes,
98            byte_len: self.byte_len,
99            security_label: self.security_label,
100        }
101    }
102
103    /// Recompute the CID from the complete manifest preimage.
104    pub fn recomputed_cid(&self) -> Result<String, CasError> {
105        let bytes = serde_json::to_vec(&self.preimage())
106            .map_err(|e| CasError::Manifest(format!("serialize manifest preimage: {e}")))?;
107        let digest = blake3::hash(&bytes);
108        encode_cid(
109            FILE_RECONSTRUCTION_CODEC,
110            HashAlgo::Blake3,
111            digest.as_bytes(),
112        )
113        .map_err(|e| CasError::Cid(e.to_string()))
114    }
115}
116
117impl LabeledObject for BlobManifest {
118    fn security_label(&self) -> Option<SecurityLabel> {
119        Some(self.security_label)
120    }
121}
122
123impl ContentBoundLabel for BlobManifest {
124    fn content_id(&self) -> &[u8] {
125        self.cid.as_bytes()
126    }
127
128    fn verify_binding(&self) -> bool {
129        self.recomputed_cid().is_ok_and(|cid| cid == self.cid)
130    }
131}
132
133/// Encode a legacy XET merkle hex digest as a canonical CIDv1 for the given
134/// algorithm, using the reconstruction-shard codec.
135pub fn cid_from_merkle(algorithm: HashAlgo, merkle_hex: &str) -> Result<String, CasError> {
136    let digest = hex::decode(merkle_hex).map_err(|e| CasError::Hex(e.to_string()))?;
137    encode_cid(Codec::XetShard, algorithm, &digest).map_err(|e| CasError::Cid(e.to_string()))
138}
139
140/// Resolve a legacy caller-supplied reconstruction address to the hex digest the
141/// underlying `cas_serve::CasStore` keys on.
142///
143/// Accepts **either**:
144/// - a legacy reconstruction CIDv1 string (`b…` base32 multibase) — decoded to
145///   its digest, or
146/// - a legacy bare hex merkle (40 or 64 hex chars) — returned lowercased.
147///
148/// A labeled manifest CID deliberately cannot be reduced to a merkle: it must be
149/// resolved through its persisted manifest so the label binding is verified.
150pub fn merkle_from_address(address: &str) -> Result<String, CasError> {
151    if looks_like_legacy_hex(address) {
152        return Ok(address.to_ascii_lowercase());
153    }
154    let cid = decode_cid(address).map_err(|e| CasError::Cid(e.to_string()))?;
155    if cid.codec != Codec::XetShard {
156        return Err(CasError::Cid(
157            "manifest CID must be resolved through the sealed manifest store".into(),
158        ));
159    }
160    Ok(hex::encode(cid.multihash.digest))
161}
162
163/// Whether `address` is a legacy bare SHA-1 or BLAKE3 merkle digest.
164///
165/// This predicate selects the compatibility path that bypasses sealed-manifest
166/// resolution, so all CAS callers must share this single definition.
167pub(crate) fn looks_like_legacy_hex(address: &str) -> bool {
168    matches!(address.len(), 40 | 64) && address.bytes().all(|b| b.is_ascii_hexdigit())
169}
170
171#[cfg(test)]
172#[allow(clippy::unwrap_used, clippy::expect_used)]
173mod tests {
174    use super::*;
175
176    #[test]
177    fn cid_from_merkle_round_trips_via_address() {
178        // 32-byte blake3 merkle → CID → back to the same hex digest.
179        let merkle = "ab".repeat(32);
180        let cid = cid_from_merkle(HashAlgo::Blake3, &merkle).unwrap();
181        assert!(cid.starts_with('b'), "canonical CIDv1 base32 prefix");
182        let back = merkle_from_address(&cid).unwrap();
183        assert_eq!(back, merkle);
184    }
185
186    #[test]
187    fn legacy_hex_merkle_passes_through() {
188        let merkle = "cd".repeat(32); // 64 hex chars
189        assert_eq!(merkle_from_address(&merkle).unwrap(), merkle);
190        // Uppercase legacy hex is normalized to lowercase.
191        assert_eq!(merkle_from_address(&merkle.to_uppercase()).unwrap(), merkle);
192        // A 40-char (sha1) legacy digest is also accepted.
193        let sha1 = "ef".repeat(20);
194        assert_eq!(merkle_from_address(&sha1).unwrap(), sha1);
195    }
196
197    #[test]
198    fn cid_and_legacy_hex_resolve_identically() {
199        let merkle = "12".repeat(32);
200        let cid = cid_from_merkle(HashAlgo::Blake3, &merkle).unwrap();
201        assert_eq!(
202            merkle_from_address(&cid).unwrap(),
203            merkle_from_address(&merkle).unwrap(),
204            "a CID and its legacy hex must resolve to the same store key"
205        );
206    }
207
208    #[test]
209    fn rejects_garbage_address() {
210        // Not 40/64 hex, not a valid CID.
211        assert!(merkle_from_address("not-an-address").is_err());
212        assert!(cid_from_merkle(HashAlgo::Blake3, "zz").is_err());
213    }
214
215    #[test]
216    fn sealed_manifest_serializes_with_a_required_label() {
217        use hyprstream_rpc::auth::mac::{Assurance, CompartmentSet, Level};
218        let label =
219            SecurityLabel::new(Level::Internal, Assurance::Classical, CompartmentSet::EMPTY);
220        let m = BlobManifest::new("ab".repeat(32), vec!["cd".repeat(32)], 42, 100, label).unwrap();
221        let json = serde_json::to_string(&m).unwrap();
222        let back: BlobManifest = serde_json::from_str(&json).unwrap();
223        assert_eq!(back, m);
224        assert_eq!(back.security_label, label);
225        assert!(back.verify_binding());
226    }
227
228    #[test]
229    fn changing_a_label_rehashes_the_manifest_cid() {
230        use hyprstream_rpc::auth::mac::{Assurance, CompartmentSet, Level};
231        let internal =
232            SecurityLabel::new(Level::Internal, Assurance::Classical, CompartmentSet::EMPTY);
233        let secret = SecurityLabel::new(Level::Secret, Assurance::Classical, CompartmentSet::EMPTY);
234        let a = BlobManifest::new("ab".repeat(32), vec![], 0, 100, internal).unwrap();
235        let b = BlobManifest::new("ab".repeat(32), vec![], 0, 100, secret).unwrap();
236        assert_ne!(a.cid, b.cid, "relabeling must rehash the manifest");
237    }
238}