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}