Skip to main content

ask/store/
mod.rs

1//! Global ASK store — atomic writes, entry locking, content verification, the
2//! store-version marker, and quarantine. Rust port of `store/index.ts`.
3//!
4//! The `github/db` and `github/checkouts` legacy layouts are intentionally NOT
5//! reintroduced (see CLAUDE.md); only cache cleanup references them by name.
6
7pub mod cache;
8mod paths;
9
10pub use paths::{
11    assert_contained, assert_safe_segment, github_store_path, lexical_clean, llms_txt_store_path,
12    normalize_url, npm_store_path, resolve_ask_home, web_store_path,
13};
14
15use std::path::{Path, PathBuf};
16use std::sync::atomic::{AtomicU64, Ordering};
17use std::time::{Duration, Instant, SystemTime};
18
19use sha2::{Digest, Sha256};
20
21const HASH_FILE: &str = ".ask-hash";
22const STORE_VERSION_FILE: &str = "STORE_VERSION";
23const CURRENT_STORE_VERSION: &str = "2";
24
25/// A file to write into a store entry: a relative path and its text content.
26pub struct EntryFile {
27    pub path: String,
28    pub content: String,
29}
30
31/// A short random-ish hex suffix for temp/backup directory names. Uniqueness is
32/// only needed to avoid same-process collisions (the entry lock serializes real
33/// writers), so SystemTime nanos XOR a process-lifetime counter suffices.
34fn rand_hex8() -> String {
35    static COUNTER: AtomicU64 = AtomicU64::new(0);
36    let nanos = SystemTime::now()
37        .duration_since(SystemTime::UNIX_EPOCH)
38        .map(|d| d.as_nanos() as u64)
39        .unwrap_or(0);
40    let n = nanos
41        ^ (COUNTER
42            .fetch_add(1, Ordering::Relaxed)
43            .wrapping_mul(0x9E37_79B9_7F4A_7C15));
44    format!("{:08x}", (n as u32))
45}
46
47/// Atomically swap `tmp_dir` into `target`: rename any existing target to a
48/// backup first (keeping the path continuously observable), move tmp into place,
49/// then remove the backup. Restores the original on a failed move.
50fn atomic_swap(tmp_dir: &Path, target: &Path) -> std::io::Result<()> {
51    if target.exists() {
52        let backup = sibling(target, ".bak-");
53        std::fs::rename(target, &backup)?;
54        if let Err(e) = std::fs::rename(tmp_dir, target) {
55            let _ = std::fs::rename(&backup, target);
56            return Err(e);
57        }
58        let _ = std::fs::remove_dir_all(&backup);
59    } else {
60        std::fs::rename(tmp_dir, target)?;
61    }
62    Ok(())
63}
64
65fn sibling(target: &Path, infix: &str) -> PathBuf {
66    let name = target
67        .file_name()
68        .map(|n| n.to_string_lossy().into_owned())
69        .unwrap_or_default();
70    target.with_file_name(format!("{name}{infix}{}", rand_hex8()))
71}
72
73/// Atomically write a directory of files to `target_dir` (temp dir + rename).
74/// Each file path is containment-checked so a malicious archive entry
75/// (`../../etc/passwd`) cannot escape.
76pub fn write_entry_atomic(target_dir: &Path, files: &[EntryFile]) -> anyhow::Result<()> {
77    let tmp_dir = sibling(target_dir, ".tmp-");
78    std::fs::create_dir_all(&tmp_dir)?;
79    let result = (|| -> anyhow::Result<()> {
80        for file in files {
81            let file_path = tmp_dir.join(&file.path);
82            assert_contained(&tmp_dir, &file_path)?;
83            if let Some(parent) = file_path.parent() {
84                std::fs::create_dir_all(parent)?;
85            }
86            std::fs::write(&file_path, &file.content)?;
87        }
88        atomic_swap(&tmp_dir, target_dir)?;
89        Ok(())
90    })();
91    if result.is_err() {
92        let _ = std::fs::remove_dir_all(&tmp_dir);
93    }
94    result
95}
96
97/// Atomically copy a directory tree to `target_dir`, preserving symlinks
98/// **verbatim** (not resolving them against the source). Without this, relative
99/// symlinks would bake in absolute paths pointing at the soon-deleted clone tmp
100/// dir, breaking every later `verify_entry` with ENOENT (the gitbutler CLAUDE.md
101/// symlink gotcha).
102pub fn cp_dir_atomic(source_dir: &Path, target_dir: &Path) -> anyhow::Result<()> {
103    let tmp_dir = sibling(target_dir, ".tmp-");
104    if let Some(parent) = tmp_dir.parent() {
105        std::fs::create_dir_all(parent)?;
106    }
107    let result = (|| -> anyhow::Result<()> {
108        // `source_dir` is the containment root: a (non-unix) symlink whose target
109        // dereferences outside it must not pull unrelated files into the entry.
110        copy_tree_verbatim(source_dir, source_dir, &tmp_dir)?;
111        atomic_swap(&tmp_dir, target_dir)?;
112        Ok(())
113    })();
114    if result.is_err() {
115        let _ = std::fs::remove_dir_all(&tmp_dir);
116    }
117    result
118}
119
120/// Recursively copy `src` into `dst`, copying symlinks as symlinks (verbatim
121/// target) rather than following them.
122fn copy_tree_verbatim(root: &Path, src: &Path, dst: &Path) -> anyhow::Result<()> {
123    std::fs::create_dir_all(dst)?;
124    for entry in std::fs::read_dir(src)? {
125        let entry = entry?;
126        let file_type = entry.file_type()?;
127        let from = entry.path();
128        let to = dst.join(entry.file_name());
129        if file_type.is_symlink() {
130            let target = std::fs::read_link(&from)?;
131            symlink_verbatim(root, &target, &from, &to)?;
132        } else if file_type.is_dir() {
133            copy_tree_verbatim(root, &from, &to)?;
134        } else {
135            std::fs::copy(&from, &to)?;
136        }
137    }
138    Ok(())
139}
140
141#[cfg(unix)]
142fn symlink_verbatim(
143    _root: &Path,
144    target: &Path,
145    _src_link: &Path,
146    link: &Path,
147) -> std::io::Result<()> {
148    // Unix records the link verbatim — it never dereferences the target, so an
149    // escaping target is just a link, not a copy of external content.
150    std::os::unix::fs::symlink(target, link)
151}
152
153#[cfg(not(unix))]
154fn symlink_verbatim(
155    root: &Path,
156    target: &Path,
157    src_link: &Path,
158    link: &Path,
159) -> std::io::Result<()> {
160    // Windows requires privileges/target-type for symlinks; fall back to copying
161    // the resolved file (best-effort; the store gotchas this guards are unix).
162    // `target` may be RELATIVE to the source link's directory, so resolve it
163    // against `src_link.parent()` before copying — copying the raw relative
164    // target would resolve against the process CWD and read the wrong file / fail.
165    let resolved = if target.is_absolute() {
166        target.to_path_buf()
167    } else {
168        src_link
169            .parent()
170            .unwrap_or_else(|| Path::new("."))
171            .join(target)
172    };
173    // Containment: unlike unix (which only records the link), this branch COPIES
174    // the target's bytes into the entry. A symlink whose target dereferences
175    // outside the copy root (`../…`, an absolute path, or an escaping chain)
176    // would exfiltrate unrelated local files into the cached entry — so canonicalize
177    // both and skip the entry when the target escapes the root or cannot be resolved.
178    match (
179        std::fs::canonicalize(root),
180        std::fs::canonicalize(&resolved),
181    ) {
182        (Ok(real_root), Ok(real_target)) if real_target.starts_with(&real_root) => {
183            std::fs::copy(&real_target, link).map(|_| ())
184        }
185        _ => Ok(()), // escapes the root or unresolvable → skip, do not exfiltrate
186    }
187}
188
189// ── Entry locking ──────────────────────────────────────────────────
190
191const LOCK_TIMEOUT: Duration = Duration::from_secs(60);
192const LOCK_INITIAL_DELAY: Duration = Duration::from_millis(100);
193const LOCK_MAX_DELAY: Duration = Duration::from_millis(1600);
194
195/// An acquired entry lock; removes its lock file on drop.
196pub struct EntryLock {
197    lock_path: PathBuf,
198}
199
200impl Drop for EntryLock {
201    fn drop(&mut self) {
202        let _ = std::fs::remove_file(&self.lock_path);
203    }
204}
205
206/// Acquire a per-entry advisory lock (`<entry>.lock`, exclusive-create) with
207/// exponential backoff. Returns `Ok(None)` when the target entry appears while
208/// waiting (another process finished the write — treat as a hit). Errors on
209/// timeout without deleting the live lock.
210pub fn acquire_entry_lock(entry_dir: &Path) -> anyhow::Result<Option<EntryLock>> {
211    let lock_path = {
212        let name = entry_dir
213            .file_name()
214            .map(|n| n.to_string_lossy().into_owned())
215            .unwrap_or_default();
216        entry_dir.with_file_name(format!("{name}.lock"))
217    };
218    if let Some(parent) = lock_path.parent() {
219        std::fs::create_dir_all(parent)?;
220    }
221
222    let deadline = Instant::now() + LOCK_TIMEOUT;
223    let mut delay = LOCK_INITIAL_DELAY;
224
225    loop {
226        match std::fs::OpenOptions::new()
227            .write(true)
228            .create_new(true)
229            .open(&lock_path)
230        {
231            Ok(_) => return Ok(Some(EntryLock { lock_path })),
232            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
233                // Held elsewhere. If the target now exists, another process
234                // finished — treat as a store hit.
235                if entry_dir.exists() {
236                    return Ok(None);
237                }
238                if Instant::now() >= deadline {
239                    anyhow::bail!(
240                        "Timed out waiting for lock: {}. Another ask install may be in progress. \
241                         If no other process is running, remove it manually.",
242                        lock_path.display()
243                    );
244                }
245                std::thread::sleep(delay);
246                delay = (delay * 2).min(LOCK_MAX_DELAY);
247            }
248            Err(e) => return Err(e.into()),
249        }
250    }
251}
252
253// ── Content verification ───────────────────────────────────────────
254
255/// Compute and record a content hash for a finalized entry (`.ask-hash`).
256pub fn stamp_entry(entry_dir: &Path) -> anyhow::Result<String> {
257    let hash = hash_dir(entry_dir)?;
258    std::fs::write(entry_dir.join(HASH_FILE), &hash)?;
259    Ok(hash)
260}
261
262/// Whether an entry's recorded `.ask-hash` matches its recomputed hash.
263pub fn verify_entry(entry_dir: &Path) -> bool {
264    let hash_path = entry_dir.join(HASH_FILE);
265    let Ok(recorded) = std::fs::read_to_string(&hash_path) else {
266        return false;
267    };
268    match hash_dir(entry_dir) {
269        Ok(actual) => recorded.trim() == actual,
270        Err(_) => false,
271    }
272}
273
274/// sha256 over the sorted relative file list, `<relpath>\0<bytes>\0` per file,
275/// skipping the `.ask-hash` file itself.
276fn hash_dir(dir: &Path) -> anyhow::Result<String> {
277    let mut files = collect_files(dir, "")?;
278    files.sort();
279    let mut hasher = Sha256::new();
280    for rel in &files {
281        if Path::new(rel).file_name().and_then(|n| n.to_str()) == Some(HASH_FILE) {
282            continue;
283        }
284        hasher.update(rel.as_bytes());
285        hasher.update([0u8]);
286        hasher.update(std::fs::read(dir.join(rel))?);
287        hasher.update([0u8]);
288    }
289    Ok(format!("sha256-{:x}", hasher.finalize()))
290}
291
292/// Relative file paths under `dir` (recursive, forward-slash separated).
293fn collect_files(dir: &Path, prefix: &str) -> anyhow::Result<Vec<String>> {
294    let mut out = Vec::new();
295    for entry in std::fs::read_dir(dir)? {
296        let entry = entry?;
297        let name = entry.file_name().to_string_lossy().into_owned();
298        let rel = if prefix.is_empty() {
299            name.clone()
300        } else {
301            format!("{prefix}/{name}")
302        };
303        if entry.file_type()?.is_dir() {
304            out.extend(collect_files(&entry.path(), &rel)?);
305        } else {
306            out.push(rel);
307        }
308    }
309    Ok(out)
310}
311
312// ── Store version ──────────────────────────────────────────────────
313
314/// Write `<askHome>/STORE_VERSION` if absent or stale (best-effort).
315pub fn write_store_version(ask_home: &Path) {
316    let file = ask_home.join(STORE_VERSION_FILE);
317    let _ = std::fs::create_dir_all(ask_home);
318    let existing = std::fs::read_to_string(&file)
319        .ok()
320        .map(|s| s.trim().to_string());
321    if existing.as_deref() != Some(CURRENT_STORE_VERSION) {
322        let _ = std::fs::write(&file, format!("{CURRENT_STORE_VERSION}\n"));
323    }
324}
325
326/// Read `<askHome>/STORE_VERSION`, or `None` for a fresh/pre-v2 store.
327pub fn read_store_version(ask_home: &Path) -> Option<String> {
328    std::fs::read_to_string(ask_home.join(STORE_VERSION_FILE))
329        .ok()
330        .map(|s| s.trim().to_string())
331}
332
333// ── Quarantine ─────────────────────────────────────────────────────
334
335/// Move a corrupt entry (one failing `verify_entry`) to
336/// `<askHome>/.quarantine/<ts>-<rand>/` for inspection; a rename failure falls
337/// back to a best-effort remove.
338pub fn quarantine_entry(ask_home: &Path, store_dir: &Path) {
339    let ts = SystemTime::now()
340        .duration_since(SystemTime::UNIX_EPOCH)
341        .map(|d| d.as_secs())
342        .unwrap_or(0);
343    let quarantine_dir = ask_home
344        .join(".quarantine")
345        .join(format!("{ts}-{}", rand_hex8()));
346    if let Some(parent) = quarantine_dir.parent() {
347        let _ = std::fs::create_dir_all(parent);
348    }
349    if std::fs::rename(store_dir, &quarantine_dir).is_err() {
350        let _ = std::fs::remove_dir_all(store_dir);
351    }
352}
353
354#[cfg(test)]
355mod tests {
356    use super::*;
357
358    fn ef(path: &str, content: &str) -> EntryFile {
359        EntryFile {
360            path: path.into(),
361            content: content.into(),
362        }
363    }
364
365    #[test]
366    fn write_then_verify_roundtrip() {
367        let dir = tempfile::tempdir().unwrap();
368        let target = dir.path().join("entry");
369        write_entry_atomic(&target, &[ef("INDEX.md", "hi"), ef("sub/a.md", "x")]).unwrap();
370        assert_eq!(
371            std::fs::read_to_string(target.join("INDEX.md")).unwrap(),
372            "hi"
373        );
374        assert_eq!(
375            std::fs::read_to_string(target.join("sub/a.md")).unwrap(),
376            "x"
377        );
378
379        stamp_entry(&target).unwrap();
380        assert!(verify_entry(&target));
381        // Tamper → verification fails.
382        std::fs::write(target.join("INDEX.md"), "changed").unwrap();
383        assert!(!verify_entry(&target));
384    }
385
386    #[test]
387    fn write_entry_rejects_escaping_path() {
388        let dir = tempfile::tempdir().unwrap();
389        let target = dir.path().join("entry");
390        assert!(write_entry_atomic(&target, &[ef("../escape.md", "x")]).is_err());
391    }
392
393    #[test]
394    fn write_entry_overwrites_existing_atomically() {
395        let dir = tempfile::tempdir().unwrap();
396        let target = dir.path().join("entry");
397        write_entry_atomic(&target, &[ef("a.md", "1")]).unwrap();
398        write_entry_atomic(&target, &[ef("b.md", "2")]).unwrap();
399        // The second write replaced the first entirely.
400        assert!(!target.join("a.md").exists());
401        assert_eq!(std::fs::read_to_string(target.join("b.md")).unwrap(), "2");
402    }
403
404    #[cfg(unix)]
405    #[test]
406    fn cp_dir_preserves_symlinks_verbatim() {
407        let dir = tempfile::tempdir().unwrap();
408        let src = dir.path().join("src");
409        std::fs::create_dir_all(&src).unwrap();
410        std::fs::write(src.join("AGENTS.md"), "agents").unwrap();
411        std::os::unix::fs::symlink("AGENTS.md", src.join("CLAUDE.md")).unwrap();
412
413        let target = dir.path().join("dst");
414        cp_dir_atomic(&src, &target).unwrap();
415        let link = target.join("CLAUDE.md");
416        assert!(link.symlink_metadata().unwrap().file_type().is_symlink());
417        // The relative target is preserved verbatim (not absolutized).
418        assert_eq!(std::fs::read_link(&link).unwrap(), Path::new("AGENTS.md"));
419        assert_eq!(std::fs::read_to_string(&link).unwrap(), "agents");
420    }
421
422    #[test]
423    fn lock_acquire_release_and_hit() {
424        let dir = tempfile::tempdir().unwrap();
425        let entry = dir.path().join("e");
426        let lock = acquire_entry_lock(&entry).unwrap().unwrap();
427        assert!(dir.path().join("e.lock").exists());
428        drop(lock);
429        assert!(!dir.path().join("e.lock").exists());
430
431        // Lock held + target exists → treated as a hit (None).
432        std::fs::create_dir_all(&entry).unwrap();
433        let _held = std::fs::OpenOptions::new()
434            .write(true)
435            .create_new(true)
436            .open(dir.path().join("e.lock"))
437            .unwrap();
438        assert!(acquire_entry_lock(&entry).unwrap().is_none());
439    }
440
441    #[test]
442    fn store_version_roundtrip() {
443        let dir = tempfile::tempdir().unwrap();
444        assert_eq!(read_store_version(dir.path()), None);
445        write_store_version(dir.path());
446        assert_eq!(read_store_version(dir.path()).as_deref(), Some("2"));
447    }
448
449    #[test]
450    fn quarantine_moves_entry_out() {
451        let dir = tempfile::tempdir().unwrap();
452        let store = dir.path().join("npm").join("bad@1.0.0");
453        std::fs::create_dir_all(&store).unwrap();
454        std::fs::write(store.join("x"), "y").unwrap();
455        quarantine_entry(dir.path(), &store);
456        assert!(!store.exists());
457        assert!(dir
458            .path()
459            .join(".quarantine")
460            .read_dir()
461            .unwrap()
462            .next()
463            .is_some());
464    }
465}