Skip to main content

rf_cache/
store.rs

1//! The on-disk cache itself: authenticated entries, restrictive
2//! permissions, atomic writes, and a byte-weighted LRU with a TTL.
3//!
4//! Findings closed here: CLI-07/MCP-04 (entries were trusted verbatim,
5//! deterministically named and mode 0644 — a fabricated
6//! `pop rdi ; ret @ 0xdeadbeefcafe0000` was served through the live MCP
7//! server alongside the genuine `binary_sha256`), CLI-08/PERF-12 (the CLI
8//! cache grew 5.3 MB per scan configuration in the user's home, for ever,
9//! with no eviction and no way to purge it).
10
11use std::fs::{self, File, OpenOptions};
12use std::io::Write;
13use std::path::{Path, PathBuf};
14use std::sync::atomic::{AtomicU64, Ordering};
15use std::sync::{Mutex, PoisonError};
16use std::time::{Duration, SystemTime};
17
18use crate::mac::{ct_eq, hmac_sha256, MAC_LEN};
19use crate::record::CachedScan;
20
21/// File extension for entries. Deliberately *not* `.json`: the pre-v0.2
22/// cache wrote unauthenticated `.json` files, and those must be ignored
23/// rather than parsed.
24const ENTRY_EXT: &str = "rfc";
25/// Entry frame: `MAGIC || tag[32] || body`.
26const MAGIC: &[u8; 8] = b"RFCACHE\x02";
27/// Name of the entry-authentication key inside the cache directory.
28pub const KEY_FILE: &str = ".cachekey";
29/// Length of that key.
30const KEY_LEN: usize = 32;
31
32/// Default total on-disk budget for cache entries.
33pub const DEFAULT_MAX_TOTAL_BYTES: u64 = 512 * 1024 * 1024;
34/// Default entry lifetime.
35pub const DEFAULT_TTL: Duration = Duration::from_secs(14 * 24 * 60 * 60);
36/// Default per-entry cap. Enforced by `stat` *before* the file is read, so
37/// an oversized entry never costs the memory it claims.
38pub const DEFAULT_MAX_ENTRY_BYTES: u64 = 64 * 1024 * 1024;
39
40/// CLI-08/PERF-12 budget.
41#[derive(Debug, Clone, Copy)]
42pub struct CacheLimits {
43    /// Total on-disk budget; the LRU evicts to stay under it.
44    pub max_total_bytes: u64,
45    /// How long an entry stays usable.
46    pub ttl: Duration,
47    /// Largest single entry that will be stored at all.
48    pub max_entry_bytes: u64,
49}
50
51impl Default for CacheLimits {
52    fn default() -> Self {
53        CacheLimits {
54            max_total_bytes: DEFAULT_MAX_TOTAL_BYTES,
55            ttl: DEFAULT_TTL,
56            max_entry_bytes: DEFAULT_MAX_ENTRY_BYTES,
57        }
58    }
59}
60
61impl CacheLimits {
62    /// Defaults, overridable by `ROP_FINDER_CACHE_MAX_BYTES` and
63    /// `ROP_FINDER_CACHE_TTL_SECS`. Environment rather than flags because
64    /// both front ends need them and neither has a settings file; a bad
65    /// value is ignored rather than being a startup error.
66    #[must_use]
67    pub fn from_env() -> Self {
68        let mut l = CacheLimits::default();
69        if let Some(v) = std::env::var("ROP_FINDER_CACHE_MAX_BYTES")
70            .ok()
71            .and_then(|v| v.parse::<u64>().ok())
72        {
73            l.max_total_bytes = v;
74        }
75        if let Some(v) = std::env::var("ROP_FINDER_CACHE_TTL_SECS")
76            .ok()
77            .and_then(|v| v.parse::<u64>().ok())
78        {
79            l.ttl = Duration::from_secs(v);
80        }
81        l
82    }
83}
84
85/// Counters. `tampered` is the one that matters: it is non-zero only when
86/// a file in the cache directory carried a body the cache did not write.
87#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
88pub struct CacheStats {
89    /// Lookups served from disk.
90    pub hits: u64,
91    /// Lookups that found nothing usable.
92    pub misses: u64,
93    /// Entries whose HMAC tag did not verify, or whose frame was not one
94    /// this program writes (wrong magic, truncated).
95    pub tampered: u64,
96    /// Entries that authenticated but did not [`CachedScan::validate`].
97    pub malformed: u64,
98    /// Entries dropped because they were older than the TTL.
99    pub expired: u64,
100    /// Entries written.
101    pub stored: u64,
102    /// Writes that failed (a full or read-only directory).
103    pub store_errors: u64,
104    /// Entries dropped to stay under `max_total_bytes`.
105    pub evicted: u64,
106    /// Bytes reclaimed by those evictions.
107    pub evicted_bytes: u64,
108}
109
110/// Why the on-disk cache is not available. The caller warns and continues
111/// **without** a cache: an unauthenticated read is never the fallback.
112#[derive(Debug, Clone)]
113pub struct OpenError(String);
114
115impl std::fmt::Display for OpenError {
116    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
117        f.write_str(&self.0)
118    }
119}
120
121impl std::error::Error for OpenError {}
122
123/// An opened, authenticated cache directory.
124#[derive(Debug)]
125pub struct DiskCache {
126    dir: PathBuf,
127    mac_key: [u8; KEY_LEN],
128    limits: CacheLimits,
129    stats: Mutex<CacheStats>,
130    /// Monotonic suffix so two threads in one process never pick the same
131    /// temp name.
132    seq: AtomicU64,
133}
134
135impl DiskCache {
136    /// Open (creating if necessary) the cache directory at `dir`.
137    ///
138    /// Fails — meaning *disable the cache*, not *fall back to
139    /// unauthenticated reads* — when the directory belongs to another
140    /// user, when it cannot be made private, or when the key file is
141    /// absent-and-uncreatable, the wrong length, or readable by anyone
142    /// but the owner.
143    pub fn open(dir: impl Into<PathBuf>, limits: CacheLimits) -> Result<Self, OpenError> {
144        let dir = dir.into();
145        create_private_dir(&dir)?;
146        check_dir_owner(&dir)?;
147        let mac_key = load_or_create_key(&dir)?;
148        Ok(DiskCache {
149            dir,
150            mac_key,
151            limits,
152            stats: Mutex::new(CacheStats::default()),
153            seq: AtomicU64::new(0),
154        })
155    }
156
157    /// The directory this cache lives in.
158    #[must_use]
159    pub fn dir(&self) -> &Path {
160        &self.dir
161    }
162
163    /// The budget this cache was opened with.
164    #[must_use]
165    pub fn limits(&self) -> CacheLimits {
166        self.limits
167    }
168
169    /// Snapshot of the counters.
170    #[must_use]
171    pub fn stats(&self) -> CacheStats {
172        *self.lock()
173    }
174
175    /// Poisoned-mutex policy for every cache lock: take the inner value.
176    /// The counters are plain integers, so a panic elsewhere cannot have
177    /// left them in a state that makes the *next* scan wrong, and
178    /// `.lock().unwrap()` would turn one unrelated panic into a permanent
179    /// failure of the whole cache.
180    fn lock(&self) -> std::sync::MutexGuard<'_, CacheStats> {
181        self.stats.lock().unwrap_or_else(PoisonError::into_inner)
182    }
183
184    fn bump(&self, f: impl FnOnce(&mut CacheStats)) {
185        f(&mut self.lock());
186    }
187
188    fn entry_path(&self, key: &str) -> Option<PathBuf> {
189        // A key reaches the filesystem, so it is checked as a name and not
190        // trusted to be one: no separators, no `..`, no drive letters.
191        if key.is_empty()
192            || key.len() > 256
193            || !key
194                .bytes()
195                .all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_' || b == b'.')
196            || key.starts_with('.')
197            || key.contains("..")
198        {
199            return None;
200        }
201        Some(self.dir.join(format!("{key}.{ENTRY_EXT}")))
202    }
203
204    /// Load and authenticate the entry for `key`.
205    ///
206    /// Every failure path — absent, expired, oversized, truncated, wrong
207    /// magic, bad tag, or a body that does not validate — returns `None`.
208    /// A tag mismatch also warns on stderr and bumps
209    /// [`CacheStats::tampered`].
210    #[must_use]
211    pub fn load(&self, key: &str) -> Option<CachedScan> {
212        let raw = self.load_body(key)?;
213        match serde_json::from_slice::<CachedScan>(&raw) {
214            Ok(scan) => match scan.validate() {
215                Ok(()) => {
216                    self.bump(|s| s.hits += 1);
217                    Some(scan)
218                }
219                Err(why) => {
220                    self.reject(key, &format!("entry did not validate: {why}"), true);
221                    None
222                }
223            },
224            Err(e) => {
225                self.reject(key, &format!("entry is not valid JSON: {e}"), true);
226                None
227            }
228        }
229    }
230
231    /// Store `scan` under `key`, atomically and authenticated.
232    pub fn store(&self, key: &str, scan: &CachedScan) -> Result<(), String> {
233        let body = serde_json::to_vec(scan).map_err(|e| format!("serialize: {e}"))?;
234        self.store_body(key, &body)
235    }
236
237    /// Delete every entry. Returns `(files, bytes)` removed. The key file
238    /// survives, so a purge does not invalidate anything an operator has
239    /// backed up out of band — it just empties the cache.
240    pub fn purge(&self) -> Result<(u64, u64), String> {
241        let mut files = 0;
242        let mut bytes = 0;
243        for (path, _, len) in self.entries()? {
244            if fs::remove_file(&path).is_ok() {
245                files += 1;
246                bytes += len;
247            }
248        }
249        self.bump(|s| {
250            s.evicted += files;
251            s.evicted_bytes += bytes;
252        });
253        Ok((files, bytes))
254    }
255
256    /// Total bytes currently held by entries.
257    pub fn size_on_disk(&self) -> Result<u64, String> {
258        Ok(self.entries()?.iter().map(|(_, _, len)| *len).sum())
259    }
260
261    // -- internals ---------------------------------------------------
262
263    fn load_body(&self, key: &str) -> Option<Vec<u8>> {
264        let path = self.entry_path(key)?;
265        let Ok(meta) = fs::metadata(&path) else {
266            self.bump(|s| s.misses += 1);
267            return None;
268        };
269        if meta.len() > self.limits.max_entry_bytes.saturating_add(64) {
270            // Refused by `stat`, before a byte is read.
271            self.reject(key, "entry is larger than the per-entry cap", true);
272            return None;
273        }
274        if age(&meta).is_some_and(|a| a > self.limits.ttl) {
275            let _ = fs::remove_file(&path);
276            self.bump(|s| {
277                s.expired += 1;
278                s.misses += 1;
279            });
280            return None;
281        }
282        let Ok(raw) = fs::read(&path) else {
283            self.bump(|s| s.misses += 1);
284            return None;
285        };
286        let (Some(magic), Some(tag), Some(body)) = (
287            raw.get(..MAGIC.len()),
288            raw.get(MAGIC.len()..MAGIC.len() + MAC_LEN),
289            raw.get(MAGIC.len() + MAC_LEN..),
290        ) else {
291            // Truncated file: shorter than the frame header.
292            self.reject(key, "entry is truncated", false);
293            return None;
294        };
295        if magic != MAGIC.as_slice() {
296            self.reject(key, "entry has the wrong frame magic", false);
297            return None;
298        }
299        if !ct_eq(tag, &self.tag(key, body)) {
300            self.reject(key, "entry failed its integrity check", false);
301            return None;
302        }
303        // LRU recency: the cache has no atime it can rely on (noatime,
304        // relatime, Windows defaults), so a hit republishes mtime and
305        // eviction is oldest-mtime-first. Best effort — a read-only
306        // directory still serves hits, it just evicts in the wrong order.
307        if let Ok(f) = File::options().write(true).open(&path) {
308            let _ = f.set_modified(SystemTime::now());
309        }
310        Some(body.to_vec())
311    }
312
313    fn store_body(&self, key: &str, body: &[u8]) -> Result<(), String> {
314        let Some(path) = self.entry_path(key) else {
315            self.bump(|s| s.store_errors += 1);
316            return Err(format!("refusing to use {key:?} as a cache file name"));
317        };
318        // An entry larger than the whole budget would be written and then
319        // immediately evicted by `enforce_budget`, which is pure I/O for
320        // nothing and reads as "stored" in the log. Refuse it up front.
321        let cap = self.limits.max_entry_bytes.min(self.limits.max_total_bytes);
322        if body.len() as u64 > cap {
323            self.bump(|s| s.store_errors += 1);
324            return Err(format!(
325                "result is {} bytes, over the {cap} byte cap for one entry; not cached",
326                body.len(),
327            ));
328        }
329        let mut framed = Vec::with_capacity(MAGIC.len() + MAC_LEN + body.len());
330        framed.extend_from_slice(MAGIC);
331        framed.extend_from_slice(&self.tag(key, body));
332        framed.extend_from_slice(body);
333
334        self.persist_atomically(&path, &framed).map_err(|e| {
335            self.bump(|s| s.store_errors += 1);
336            format!("{e}")
337        })?;
338        self.bump(|s| s.stored += 1);
339        // Eviction runs after the write, so the entry just stored counts
340        // against the budget like any other.
341        if let Err(e) = self.enforce_budget() {
342            return Err(format!("stored, but eviction failed: {e}"));
343        }
344        Ok(())
345    }
346
347    /// The authenticated message is `key || 0x00 || body`. The NUL keeps
348    /// the two fields unambiguous, and binding the key means an entry
349    /// cannot be renamed onto a different scan configuration.
350    fn tag(&self, key: &str, body: &[u8]) -> [u8; MAC_LEN] {
351        let mut msg = Vec::with_capacity(key.len() + 1 + body.len());
352        msg.extend_from_slice(key.as_bytes());
353        msg.push(0);
354        msg.extend_from_slice(body);
355        hmac_sha256(&self.mac_key, &msg)
356    }
357
358    /// Write to a fresh private file and rename over the entry, so a
359    /// concurrent reader sees either the whole old entry or the whole new
360    /// one — never a half-written body, and never a body with a tag from a
361    /// different write.
362    fn persist_atomically(&self, path: &Path, framed: &[u8]) -> std::io::Result<()> {
363        let n = self.seq.fetch_add(1, Ordering::Relaxed);
364        let nanos = SystemTime::now()
365            .duration_since(SystemTime::UNIX_EPOCH)
366            .map_or(0, |d| d.as_nanos());
367        let tmp = self
368            .dir
369            .join(format!(".tmp-{}-{n}-{nanos:x}", std::process::id()));
370        {
371            let mut f = private_create_new(&tmp)?;
372            f.write_all(framed)?;
373            f.sync_all()?;
374        }
375        // Windows can transiently refuse the replace while another handle
376        // is closing; std's rename replaces an existing destination on
377        // both platforms, so this is the whole atomicity story.
378        let mut last = None;
379        for _ in 0..32 {
380            match fs::rename(&tmp, path) {
381                Ok(()) => return Ok(()),
382                Err(e) => {
383                    last = Some(e);
384                    std::thread::sleep(Duration::from_millis(2));
385                }
386            }
387        }
388        let _ = fs::remove_file(&tmp);
389        Err(last.unwrap_or_else(|| std::io::Error::other("rename failed")))
390    }
391
392    /// `(path, mtime, len)` for every entry.
393    fn entries(&self) -> Result<Vec<(PathBuf, SystemTime, u64)>, String> {
394        let rd = match fs::read_dir(&self.dir) {
395            Ok(rd) => rd,
396            Err(e) => return Err(format!("{}: {e}", self.dir.display())),
397        };
398        let mut out = Vec::new();
399        for e in rd.flatten() {
400            let path = e.path();
401            if path.extension().and_then(|s| s.to_str()) != Some(ENTRY_EXT) {
402                continue;
403            }
404            if let Ok(meta) = e.metadata() {
405                let mtime = meta.modified().unwrap_or(SystemTime::UNIX_EPOCH);
406                out.push((path, mtime, meta.len()));
407            }
408        }
409        Ok(out)
410    }
411
412    /// CLI-08/PERF-12: drop expired entries, then evict oldest-first until
413    /// the directory is inside the byte budget.
414    fn enforce_budget(&self) -> Result<(), String> {
415        let mut entries = self.entries()?;
416        let now = SystemTime::now();
417        let mut evicted = 0u64;
418        let mut evicted_bytes = 0u64;
419        entries.retain(|(path, mtime, len)| {
420            let expired = now
421                .duration_since(*mtime)
422                .is_ok_and(|a| a > self.limits.ttl);
423            if expired && fs::remove_file(path).is_ok() {
424                evicted += 1;
425                evicted_bytes += *len;
426                return false;
427            }
428            true
429        });
430        let mut total: u64 = entries.iter().map(|(_, _, len)| *len).sum();
431        if total > self.limits.max_total_bytes {
432            // Byte-weighted LRU: least recently *used*, because a hit
433            // republishes mtime.
434            entries.sort_by_key(|(_, mtime, _)| *mtime);
435            for (path, _, len) in &entries {
436                if total <= self.limits.max_total_bytes {
437                    break;
438                }
439                if fs::remove_file(path).is_ok() {
440                    total = total.saturating_sub(*len);
441                    evicted += 1;
442                    evicted_bytes += *len;
443                }
444            }
445        }
446        if evicted > 0 {
447            self.bump(|s| {
448                s.evicted += evicted;
449                s.evicted_bytes += evicted_bytes;
450            });
451        }
452        Ok(())
453    }
454
455    /// One place for "this entry is not usable": counter, warning, miss.
456    /// Never an error, and never a served result.
457    fn reject(&self, key: &str, why: &str, authenticated: bool) {
458        self.bump(|s| {
459            s.misses += 1;
460            if authenticated {
461                s.malformed += 1;
462            } else {
463                s.tampered += 1;
464            }
465        });
466        eprintln!(
467            "[Cache] warning: {} for {} — ignoring it and rescanning",
468            why,
469            crate::key_prefix(key)
470        );
471    }
472}
473
474fn age(meta: &fs::Metadata) -> Option<Duration> {
475    SystemTime::now().duration_since(meta.modified().ok()?).ok()
476}
477
478// ---------------------------------------------------------------------------
479// Permissions
480// ---------------------------------------------------------------------------
481
482#[cfg(unix)]
483fn create_private_dir(dir: &Path) -> Result<(), OpenError> {
484    use std::os::unix::fs::{DirBuilderExt, PermissionsExt};
485    if !dir.exists() {
486        fs::DirBuilder::new()
487            .recursive(true)
488            .mode(0o700)
489            .create(dir)
490            .map_err(|e| OpenError(format!("cannot create {}: {e}", dir.display())))?;
491    }
492    let meta =
493        fs::metadata(dir).map_err(|e| OpenError(format!("cannot stat {}: {e}", dir.display())))?;
494    if !meta.is_dir() {
495        return Err(OpenError(format!("{} is not a directory", dir.display())));
496    }
497    if meta.permissions().mode() & 0o077 != 0 {
498        fs::set_permissions(dir, fs::Permissions::from_mode(0o700)).map_err(|e| {
499            OpenError(format!(
500                "{} is group/world accessible and cannot be tightened: {e}",
501                dir.display()
502            ))
503        })?;
504    }
505    Ok(())
506}
507
508#[cfg(not(unix))]
509fn create_private_dir(dir: &Path) -> Result<(), OpenError> {
510    // Windows: a directory created under %LOCALAPPDATA% inherits that
511    // profile's DACL, which grants the owning user and denies other
512    // non-administrative users. There is no portable chmod, and building a
513    // DACL by hand needs the Win32 security APIs; this is the documented
514    // best-effort half of CLI-07. The HMAC is what actually keeps a
515    // poisoned entry out of the output, and it is platform-independent.
516    fs::create_dir_all(dir).map_err(|e| OpenError(format!("cannot create {}: {e}", dir.display())))
517}
518
519#[cfg(unix)]
520fn check_dir_owner(dir: &Path) -> Result<(), OpenError> {
521    use std::os::unix::fs::MetadataExt;
522    let meta =
523        fs::metadata(dir).map_err(|e| OpenError(format!("cannot stat {}: {e}", dir.display())))?;
524    let me = rustix::process::getuid().as_raw();
525    if meta.uid() != me {
526        return Err(OpenError(format!(
527            "{} is owned by uid {}, not by uid {me}",
528            dir.display(),
529            meta.uid()
530        )));
531    }
532    Ok(())
533}
534
535#[cfg(not(unix))]
536fn check_dir_owner(_dir: &Path) -> Result<(), OpenError> {
537    Ok(())
538}
539
540#[cfg(unix)]
541fn private_create_new(path: &Path) -> std::io::Result<File> {
542    use std::os::unix::fs::OpenOptionsExt;
543    OpenOptions::new()
544        .write(true)
545        .create_new(true)
546        .mode(0o600)
547        .open(path)
548}
549
550#[cfg(not(unix))]
551fn private_create_new(path: &Path) -> std::io::Result<File> {
552    OpenOptions::new().write(true).create_new(true).open(path)
553}
554
555/// Read the entry-authentication key, creating it on first use.
556///
557/// The three refusals — absent-and-uncreatable, wrong length, and
558/// group/world readable — all disable the cache. That is the point: with
559/// no trustworthy key there is no way to tell a genuine entry from a
560/// planted one, and serving unauthenticated entries "just this once" is
561/// exactly the CLI-07 bug.
562fn load_or_create_key(dir: &Path) -> Result<[u8; KEY_LEN], OpenError> {
563    let path = dir.join(KEY_FILE);
564    match private_create_new(&path) {
565        Ok(mut f) => {
566            let mut key = [0u8; KEY_LEN];
567            getrandom::fill(&mut key)
568                .map_err(|e| OpenError(format!("no OS randomness for the cache key: {e}")))?;
569            f.write_all(&key)
570                .and_then(|()| f.sync_all())
571                .map_err(|e| OpenError(format!("cannot write {}: {e}", path.display())))?;
572            Ok(key)
573        }
574        Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => read_key(&path),
575        Err(e) => Err(OpenError(format!("cannot create {}: {e}", path.display()))),
576    }
577}
578
579fn read_key(path: &Path) -> Result<[u8; KEY_LEN], OpenError> {
580    let meta = fs::metadata(path)
581        .map_err(|e| OpenError(format!("cannot stat {}: {e}", path.display())))?;
582    #[cfg(unix)]
583    {
584        use std::os::unix::fs::PermissionsExt;
585        let mode = meta.permissions().mode();
586        if mode & 0o077 != 0 {
587            return Err(OpenError(format!(
588                "{} is mode {:o}; it must be readable only by its owner",
589                path.display(),
590                mode & 0o777
591            )));
592        }
593    }
594    if meta.len() != KEY_LEN as u64 {
595        return Err(OpenError(format!(
596            "{} is {} bytes; expected {KEY_LEN}",
597            path.display(),
598            meta.len()
599        )));
600    }
601    let raw =
602        fs::read(path).map_err(|e| OpenError(format!("cannot read {}: {e}", path.display())))?;
603    let mut key = [0u8; KEY_LEN];
604    if raw.len() != KEY_LEN {
605        return Err(OpenError(format!(
606            "{} is {} bytes; expected {KEY_LEN}",
607            path.display(),
608            raw.len()
609        )));
610    }
611    for (dst, src) in key.iter_mut().zip(raw.iter()) {
612        *dst = *src;
613    }
614    Ok(key)
615}