Skip to main content

hyprstream_core/storage/cas/
domain.rs

1//! Dedup domains — the `(compartment, algorithm, trust_boundary)` key that
2//! decides which content may be deduplicated against which.
3//!
4//! A domain is realized as a distinct filesystem sub-root under the substrate
5//! root, so two blobs in different domains physically cannot share a xorb — the
6//! dedup partition is structural, not a runtime check that could be forgotten.
7
8use std::path::PathBuf;
9
10use hyprstream_rpc::auth::mac::Compartment;
11use hyprstream_rpc::cid::HashAlgo;
12
13/// The storage layer / trust boundary a blob lives in.
14///
15/// Local content is **never** deduplicated against shared-remote content: doing so
16/// would turn "is this xorb already present?" into an existence/content oracle
17/// across the boundary (U5). The boundary is part of the dedup-domain key, so the
18/// two tiers get physically separate storage roots.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
20pub enum TrustBoundary {
21    /// Node-local durable serving tier — the default write destination.
22    Local,
23    /// Content that originates from, or is shared with, a remote/federated peer.
24    SharedRemote,
25}
26
27impl TrustBoundary {
28    /// Stable, path-safe token for this boundary (used in the domain sub-root).
29    const fn token(self) -> &'static str {
30        match self {
31            TrustBoundary::Local => "local",
32            TrustBoundary::SharedRemote => "shared-remote",
33        }
34    }
35}
36
37/// A dedup domain: content is only ever deduplicated against other content in the
38/// **same** domain. Keyed by:
39///
40/// - `compartment` — tenant / need-to-know isolation, drawn from the existing MAC
41///   [`Compartment`] vocabulary (e.g. `"tenant:acme"`). `None` = untenanted. This
42///   field is READ-only vocabulary reuse; the substrate never authors, derives,
43///   or enforces MAC policy from it.
44/// - `algorithm` — the multihash algorithm; SHA-1 content is never deduplicated
45///   against SHA-256 (the pair would lean on the weaker collision resistance).
46/// - `digest_length` — the multihash digest length in bytes. **Length is part of
47///   CID identity** (the multihash carries `uvarint(len)`), so it is part of the
48///   dedup key too: BLAKE3 is an XOF and `BLAKE3-512(x)[0:32] == BLAKE3-256(x)`,
49///   so a 256-bit and a 512-bit domain over the *same* content would alias if the
50///   length were dropped from the key. Two widths get distinct storage roots
51///   (#812/#881 joint decision).
52/// - `trust_boundary` — see [`TrustBoundary`].
53///
54/// The `(algorithm, digest_length)` pair is validated against
55/// [`HashAlgo::validate_digest_len`] by [`DedupDomain::new`]; the fields stay
56/// `pub` so struct-literal construction with `..DedupDomain::local_default()`
57/// remains ergonomic, but callers that vary the algorithm/length should go through
58/// [`DedupDomain::new`] to keep the pair well-formed.
59///
60/// # On-disk mapping
61///
62/// The **default** domain `(None, Blake3, 32, Local)` maps to the substrate root
63/// itself (no sub-directory), so the legacy `cas_serve::CasStore` layout and every
64/// existing caller keep working byte-for-byte. Every other domain maps to a
65/// deterministic, injective sub-path so distinct domains never collide.
66#[derive(Debug, Clone, PartialEq, Eq, Hash)]
67pub struct DedupDomain {
68    /// Need-to-know compartment (tenant scope). `None` = untenanted.
69    pub compartment: Option<Compartment>,
70    /// Multihash algorithm partition.
71    pub algorithm: HashAlgo,
72    /// Multihash digest length in bytes (part of the CID identity). Must be a
73    /// length the `algorithm` accepts (see [`HashAlgo::validate_digest_len`]).
74    pub digest_length: u16,
75    /// Storage layer / trust boundary partition.
76    pub trust_boundary: TrustBoundary,
77}
78
79impl DedupDomain {
80    /// The default domain: untenanted, BLAKE3-256, node-local. This is the domain
81    /// the current registry/XET call sites use, and it maps to the substrate root
82    /// (legacy layout, byte-for-byte parity).
83    pub fn local_default() -> Self {
84        Self {
85            compartment: None,
86            algorithm: HashAlgo::Blake3,
87            digest_length: 32,
88            trust_boundary: TrustBoundary::Local,
89        }
90    }
91
92    /// A node-local, BLAKE3-256 domain scoped to a single tenant compartment.
93    pub fn local_tenant(compartment: Compartment) -> Self {
94        Self {
95            compartment: Some(compartment),
96            algorithm: HashAlgo::Blake3,
97            digest_length: 32,
98            trust_boundary: TrustBoundary::Local,
99        }
100    }
101
102    /// Construct a domain, validating that `(algorithm, digest_length)` is a
103    /// well-formed multihash pair (the length is one the algorithm accepts).
104    ///
105    /// This is the constructor to use when varying the algorithm or width; the
106    /// compartment/trust-boundary default to untenanted/local. Prefer
107    /// [`local_default`](Self::local_default) /
108    /// [`local_tenant`](Self::local_tenant) for the common BLAKE3-256 cases.
109    pub fn new(
110        algorithm: HashAlgo,
111        digest_length: u16,
112        compartment: Option<Compartment>,
113        trust_boundary: TrustBoundary,
114    ) -> Result<Self, InvalidDedupDomain> {
115        if algorithm
116            .validate_digest_len(digest_length as usize)
117            .is_err()
118        {
119            return Err(InvalidDedupDomain {
120                algorithm,
121                digest_length,
122            });
123        }
124        Ok(Self {
125            compartment,
126            algorithm,
127            digest_length,
128            trust_boundary,
129        })
130    }
131
132    /// True for the default domain (root-mapped, legacy-compatible).
133    pub fn is_default(&self) -> bool {
134        self.compartment.is_none()
135            && self.algorithm == HashAlgo::Blake3
136            && self.digest_length == 32
137            && self.trust_boundary == TrustBoundary::Local
138    }
139
140    /// Relative sub-path (under the substrate root) isolating this domain's blobs.
141    ///
142    /// - Default domain → empty (the root itself), preserving the legacy layout.
143    /// - Otherwise →
144    ///   `domains/<boundary>/algo-<code>-len<N>/c-<hex(compartment)|none>/`.
145    ///
146    /// The `algo-<code>-len<N>` segment encodes **both** the algorithm code and
147    /// the digest length, so two widths of the same algorithm (BLAKE3-256 vs
148    /// BLAKE3-512) map to distinct sub-roots and cannot share xorbs. The
149    /// compartment name is hex-encoded so the mapping is injective and path-safe
150    /// regardless of the characters a compartment name contains (e.g. the `:` in
151    /// `"tenant:acme"`), and can never traverse out of the root.
152    pub fn relative_path(&self) -> PathBuf {
153        if self.is_default() {
154            return PathBuf::new();
155        }
156        let compartment = match &self.compartment {
157            Some(c) => format!("c-{}", hex::encode(c.as_str().as_bytes())),
158            None => "c-none".to_owned(),
159        };
160        PathBuf::from("domains")
161            .join(self.trust_boundary.token())
162            .join(format!(
163                "algo-{:#x}-len{}",
164                self.algorithm as u64, self.digest_length
165            ))
166            .join(compartment)
167    }
168}
169
170/// Error returned by [`DedupDomain::new`] when the `(algorithm, digest_length)`
171/// pair is not a well-formed multihash pair (e.g. sha1/32, blake3/48).
172#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
173#[error(
174    "invalid dedup domain: algorithm {algorithm:?} does not accept digest length {digest_length}"
175)]
176pub struct InvalidDedupDomain {
177    pub algorithm: HashAlgo,
178    pub digest_length: u16,
179}
180
181#[cfg(test)]
182#[allow(clippy::unwrap_used, clippy::expect_used)]
183mod tests {
184    use super::*;
185
186    #[test]
187    fn default_domain_maps_to_root() {
188        let d = DedupDomain::local_default();
189        assert!(d.is_default());
190        assert_eq!(
191            d.relative_path(),
192            PathBuf::new(),
193            "default domain is the root"
194        );
195    }
196
197    #[test]
198    fn distinct_domains_map_to_distinct_paths() {
199        // Every axis change must produce a distinct storage sub-root, or two
200        // domains would share xorbs (the exact leak the domain key prevents).
201        let base = DedupDomain::local_default();
202        let other_algo = DedupDomain {
203            algorithm: HashAlgo::Sha2_256,
204            digest_length: 32,
205            ..DedupDomain::local_default()
206        };
207        let other_boundary = DedupDomain {
208            trust_boundary: TrustBoundary::SharedRemote,
209            ..DedupDomain::local_default()
210        };
211        let tenant_a = DedupDomain::local_tenant(Compartment::new("tenant:acme"));
212        let tenant_b = DedupDomain::local_tenant(Compartment::new("tenant:beta"));
213
214        let paths = [
215            base.relative_path(),
216            other_algo.relative_path(),
217            other_boundary.relative_path(),
218            tenant_a.relative_path(),
219            tenant_b.relative_path(),
220        ];
221        // All five must be pairwise distinct.
222        for i in 0..paths.len() {
223            for j in (i + 1)..paths.len() {
224                assert_ne!(paths[i], paths[j], "domains {i} and {j} collide on disk");
225            }
226        }
227    }
228
229    #[test]
230    fn blake3_256_and_512_widths_do_not_alias() {
231        // The #812/#881 joint-decision guarantee: BLAKE3 is an XOF and
232        // BLAKE3-512(x)[0:32] == BLAKE3-256(x), so the two widths MUST get
233        // distinct storage roots or a 512-bit address would dedup against — and
234        // leak the existence of — its 256-bit prefix domain.
235        //
236        // Use a tenant compartment so *neither* domain collapses to the default
237        // root (Blake3/32/None/Local); we want to compare two real sub-paths and
238        // see the length encoded in each.
239        let tenant = Some(Compartment::new("tenant:acme"));
240        let w256 =
241            DedupDomain::new(HashAlgo::Blake3, 32, tenant.clone(), TrustBoundary::Local).unwrap();
242        let w512 = DedupDomain::new(HashAlgo::Blake3, 64, tenant, TrustBoundary::Local).unwrap();
243        let p256 = w256.relative_path();
244        let p512 = w512.relative_path();
245        assert_ne!(
246            p256, p512,
247            "BLAKE3-256 and BLAKE3-512 domains must not share a storage root"
248        );
249        // The path must encode the length so the distinction is self-describing.
250        assert!(
251            p256.to_string_lossy().contains("len32"),
252            "256-bit domain path must carry len32: {p256:?}"
253        );
254        assert!(
255            p512.to_string_lossy().contains("len64"),
256            "512-bit domain path must carry len64: {p512:?}"
257        );
258    }
259
260    #[test]
261    fn new_rejects_malformed_algo_length_pair() {
262        // sha1 only accepts 20 bytes; 32 is not a valid sha1 multihash.
263        let err = DedupDomain::new(HashAlgo::Sha1, 32, None, TrustBoundary::Local).unwrap_err();
264        assert_eq!(err.algorithm, HashAlgo::Sha1);
265        assert_eq!(err.digest_length, 32);
266        // blake3 accepts 32 or 64, not 48.
267        assert!(DedupDomain::new(HashAlgo::Blake3, 48, None, TrustBoundary::Local).is_err());
268        // Valid pairs construct fine.
269        assert!(DedupDomain::new(HashAlgo::Blake3, 64, None, TrustBoundary::Local).is_ok());
270        assert!(DedupDomain::new(HashAlgo::Sha2_256, 32, None, TrustBoundary::Local).is_ok());
271    }
272
273    #[test]
274    fn compartment_path_is_traversal_safe() {
275        // A hostile-looking compartment name must not escape the root.
276        let d = DedupDomain::local_tenant(Compartment::new("../../etc/passwd"));
277        let p = d.relative_path();
278        assert!(
279            p.components()
280                .all(|c| !matches!(c, std::path::Component::ParentDir)),
281            "compartment name must never yield a `..` component: {p:?}"
282        );
283    }
284
285    #[test]
286    fn same_domain_is_stable() {
287        let a = DedupDomain::local_tenant(Compartment::new("tenant:acme"));
288        let b = DedupDomain::local_tenant(Compartment::new("tenant:acme"));
289        assert_eq!(a.relative_path(), b.relative_path());
290    }
291}