Skip to main content

hyprstream_core/services/
xet_provenance.rs

1//! XET content provenance store (the #436 / #509 fix).
2//!
3//! # Why this exists
4//!
5//! The XET CAS is **global and content-addressed**: bytes are deduplicated by
6//! their computed merkle root with no per-tenant namespacing. The pre-existing
7//! `getBlob` authorization (condition (b)) decided entitlement from a git-xet /
8//! git-lfs **pointer blob committed into the grant repo's HEAD tree**. That
9//! pointer is **caller-committed and therefore forgeable**: Tenant B can commit
10//! `oid sha256:<Tenant A's private merkle>` into their own repo and read A's
11//! private bytes back over the shared CAS. The pointer-only check structurally
12//! cannot tell a *planted* reference from a *genuine* one.
13//!
14//! # What this provides
15//!
16//! A persisted, **server-side-only** mapping `merkle_hex → {repo_id, …}` recording
17//! which repositories actually *contributed* (uploaded) the bytes behind a merkle.
18//! The bytes themselves remain globally deduplicated in the CAS — only this
19//! provenance mapping is per-repo. The read gate consults this store and **fails
20//! closed**: if no provenance record binds the merkle to the grant repo, the
21//! request is denied. A forgeable pointer can never, on its own, grant access.
22//!
23//! # Trust boundary (load-bearing)
24//!
25//! `record()` is the *only* mutating entry point and MUST be called exclusively
26//! from a **server-authenticated** code path that has already established the
27//! pushing repo's identity (NOT from caller-supplied identity such as `$USER` or
28//! a request field). See the module-level note in `registry.rs` for the wiring
29//! status of the authenticated upload binding (issue #509, part 2).
30
31use std::collections::{HashMap, HashSet};
32use std::path::{Path, PathBuf};
33
34use anyhow::{Context, Result};
35use serde::{Deserialize, Serialize};
36use tokio::sync::RwLock;
37use tracing::{debug, warn};
38
39/// On-disk representation. Versioned so the format can evolve.
40#[derive(Debug, Default, Clone, Serialize, Deserialize)]
41struct ProvenanceFile {
42    #[serde(default = "default_version")]
43    version: String,
44    /// merkle_hex → set of repo_id (UUID strings) that uploaded these bytes.
45    #[serde(default)]
46    bindings: HashMap<String, HashSet<String>>,
47}
48
49fn default_version() -> String {
50    "1.0.0".to_owned()
51}
52
53/// Persisted `(merkle_hex → {repo_id})` provenance mapping for XET CAS content.
54///
55/// Lives alongside the registry metadata (`<base_dir>/.registry/`) so it shares
56/// the registry's durability and 0600 permission posture.
57pub struct XetProvenanceStore {
58    path: PathBuf,
59    inner: RwLock<HashMap<String, HashSet<String>>>,
60}
61
62impl XetProvenanceStore {
63    /// File name within the `.registry` directory.
64    const FILE_NAME: &'static str = "xet_provenance.json";
65
66    /// Load the provenance store from `<base_dir>/.registry/xet_provenance.json`,
67    /// creating an empty in-memory store if the file does not yet exist.
68    ///
69    /// A missing file is the expected first-run state and yields an **empty**
70    /// store — which, combined with the fail-closed read gate, denies all
71    /// XetMerkle `getBlob` requests until provenance is recorded. That is the
72    /// intended secure default.
73    pub async fn load(base_dir: &Path) -> Result<Self> {
74        let path = base_dir.join(".registry").join(Self::FILE_NAME);
75        let bindings = match tokio::fs::read(&path).await {
76            Ok(bytes) => {
77                let parsed: ProvenanceFile = serde_json::from_slice(&bytes).with_context(|| {
78                    format!("failed to parse XET provenance store at {}", path.display())
79                })?;
80                debug!(
81                    entries = parsed.bindings.len(),
82                    path = %path.display(),
83                    "loaded XET provenance store"
84                );
85                parsed.bindings
86            }
87            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
88                debug!(path = %path.display(), "no XET provenance store yet; starting empty (fail-closed)");
89                HashMap::new()
90            }
91            Err(e) => {
92                return Err(e).with_context(|| {
93                    format!("failed to read XET provenance store at {}", path.display())
94                });
95            }
96        };
97        Ok(Self {
98            path,
99            inner: RwLock::new(bindings),
100        })
101    }
102
103    /// Record that `repo_id` legitimately contributed the bytes behind
104    /// `merkle_hex`, persisting the mapping.
105    ///
106    /// SECURITY: callers MUST have authenticated the pushing repo's identity
107    /// server-side before invoking this. Never pass caller-supplied identity.
108    /// The mapping is additive (global dedup means the same bytes may be
109    /// uploaded by multiple repos; each legitimately gets a binding).
110    pub async fn record(&self, merkle_hex: &str, repo_id: &str) -> Result<()> {
111        let merkle_hex = merkle_hex.trim().to_ascii_lowercase();
112        let repo_id = repo_id.trim().to_owned();
113        if merkle_hex.is_empty() || repo_id.is_empty() {
114            anyhow::bail!("record provenance denied: empty merkle or repo_id");
115        }
116        {
117            let mut guard = self.inner.write().await;
118            let entry = guard.entry(merkle_hex.clone()).or_default();
119            if !entry.insert(repo_id.clone()) {
120                // Already recorded; nothing to persist.
121                return Ok(());
122            }
123        }
124        self.persist()
125            .await
126            .with_context(|| format!("failed to persist XET provenance for merkle {merkle_hex}"))?;
127        debug!(merkle = %merkle_hex, repo = %repo_id, "recorded XET provenance");
128        Ok(())
129    }
130
131    /// Fail-closed gate check: is `merkle_hex` bound to `repo_id` by a recorded
132    /// provenance entry? Returns `false` (deny) when no record exists.
133    pub async fn is_bound(&self, merkle_hex: &str, repo_id: &str) -> bool {
134        let merkle_hex = merkle_hex.trim().to_ascii_lowercase();
135        let repo_id = repo_id.trim();
136        if merkle_hex.is_empty() || repo_id.is_empty() {
137            return false;
138        }
139        let guard = self.inner.read().await;
140        guard
141            .get(&merkle_hex)
142            .map(|repos| repos.contains(repo_id))
143            .unwrap_or(false)
144    }
145
146    /// Atomically persist the in-memory mapping to disk (tmp file + rename),
147    /// with 0600 permissions (matches the registry metadata posture).
148    async fn persist(&self) -> Result<()> {
149        let snapshot = {
150            let guard = self.inner.read().await;
151            ProvenanceFile {
152                version: default_version(),
153                bindings: guard.clone(),
154            }
155        };
156        let json = serde_json::to_vec_pretty(&snapshot)
157            .context("failed to serialize XET provenance store")?;
158
159        if let Some(parent) = self.path.parent() {
160            if let Err(e) = tokio::fs::create_dir_all(parent).await {
161                warn!(error = %e, dir = %parent.display(), "failed to ensure provenance dir");
162            }
163        }
164
165        let tmp = self.path.with_extension("json.tmp");
166        tokio::fs::write(&tmp, &json)
167            .await
168            .with_context(|| format!("failed to write provenance tmp {}", tmp.display()))?;
169
170        #[cfg(unix)]
171        {
172            use std::os::unix::fs::PermissionsExt;
173            let _ = tokio::fs::set_permissions(&tmp, std::fs::Permissions::from_mode(0o600)).await;
174        }
175
176        tokio::fs::rename(&tmp, &self.path).await.with_context(|| {
177            format!(
178                "failed to rename provenance into place {}",
179                self.path.display()
180            )
181        })?;
182        Ok(())
183    }
184}
185
186#[cfg(test)]
187#[allow(clippy::unwrap_used, clippy::expect_used)]
188mod tests {
189    use super::*;
190    use tempfile::tempdir;
191
192    // A 64-hex-char merkle stand-in for "Tenant A's private content".
193    const MERKLE_A: &str = "a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1";
194    const REPO_A: &str = "11111111-1111-1111-1111-111111111111";
195    const REPO_B: &str = "22222222-2222-2222-2222-222222222222";
196
197    async fn store_in(dir: &Path) -> XetProvenanceStore {
198        tokio::fs::create_dir_all(dir.join(".registry"))
199            .await
200            .unwrap();
201        XetProvenanceStore::load(dir).await.unwrap()
202    }
203
204    /// The core #436 / #509 invariant at the gate layer: a planted pointer with
205    /// NO provenance record must be denied (fail-closed). This is the
206    /// substantive content behind `oid_field_planted_pointer_must_be_denied`.
207    #[tokio::test]
208    async fn oid_field_planted_pointer_must_be_denied() {
209        let dir = tempdir().unwrap();
210        let store = store_in(dir.path()).await;
211
212        // Tenant A genuinely uploaded the bytes → provenance bound to repo A.
213        store.record(MERKLE_A, REPO_A).await.unwrap();
214
215        // Tenant B planted a pointer referencing A's merkle but never uploaded
216        // the bytes → NO provenance binding for repo B → MUST be denied.
217        assert!(
218            !store.is_bound(MERKLE_A, REPO_B).await,
219            "planted-pointer repo B must NOT be entitled to A's merkle"
220        );
221
222        // The legitimate owner (repo A) still resolves.
223        assert!(
224            store.is_bound(MERKLE_A, REPO_A).await,
225            "the repo that genuinely uploaded the merkle must still resolve it"
226        );
227    }
228
229    /// Fail-closed default: an unknown merkle (no record at all) is denied for
230    /// everyone — never falls back to the forgeable pointer check.
231    #[tokio::test]
232    async fn unknown_merkle_denied_fail_closed() {
233        let dir = tempdir().unwrap();
234        let store = store_in(dir.path()).await;
235        assert!(!store.is_bound(MERKLE_A, REPO_A).await);
236        assert!(!store.is_bound(MERKLE_A, REPO_B).await);
237    }
238
239    /// Records survive a reload (persistence), and case/whitespace are normalized.
240    #[tokio::test]
241    async fn provenance_persists_across_reload() {
242        let dir = tempdir().unwrap();
243        {
244            let store = store_in(dir.path()).await;
245            store
246                .record(&MERKLE_A.to_ascii_uppercase(), REPO_A)
247                .await
248                .unwrap();
249        }
250        let reloaded = XetProvenanceStore::load(dir.path()).await.unwrap();
251        assert!(reloaded.is_bound(MERKLE_A, REPO_A).await);
252        assert!(!reloaded.is_bound(MERKLE_A, REPO_B).await);
253    }
254
255    /// Global dedup: the same bytes uploaded by two repos bind to both, and each
256    /// is entitled independently.
257    #[tokio::test]
258    async fn shared_bytes_bind_per_repo() {
259        let dir = tempdir().unwrap();
260        let store = store_in(dir.path()).await;
261        store.record(MERKLE_A, REPO_A).await.unwrap();
262        store.record(MERKLE_A, REPO_B).await.unwrap();
263        assert!(store.is_bound(MERKLE_A, REPO_A).await);
264        assert!(store.is_bound(MERKLE_A, REPO_B).await);
265    }
266}