//! The only module allowed to mutate the filesystem. Every function validates its target first. use std::fs::{self, File, OpenOptions}; use std::io::{Read, Write}; use std::path::{Component, Path, PathBuf}; use sha2::{Digest, Sha256}; use crate::error::{Error, Result}; /// Resolve `.` and `..` lexically without touching the filesystem. pub fn normalize_lexical(path: &Path) -> PathBuf { let mut out = PathBuf::new(); for component in path.components() { match component { Component::CurDir => {} Component::ParentDir => { if !out.pop() { out.push(".."); } } other => out.push(other.as_os_str()), } } out } fn key(path: &Path) -> Vec { path.components() .map(|c| { let c = c.as_os_str().to_string_lossy(); if cfg!(windows) { c.to_lowercase() } else { c.into_owned() } }) .collect() } /// Component-wise prefix test: case-insensitive on Windows, exact elsewhere (`/srv/CoA` and `/srv/coa` are two folders). pub fn starts_with_ci(path: &Path, prefix: &Path) -> bool { let (p, q) = (key(path), key(prefix)); p.len() >= q.len() && p[..q.len()] == q[..] } /// Canonicalize the deepest existing ancestor, then re-append the not-yet-existing tail. /// Detects symlink / junction escapes for paths that do not exist yet. pub fn canonicalize_lenient(path: &Path) -> Result { let path = normalize_lexical(path); let mut tail: Vec = Vec::new(); let mut cursor = path.as_path(); loop { match dunce::canonicalize(cursor) { Ok(mut base) => { for part in tail.iter().rev() { base.push(part); } return Ok(base); } Err(_) => match (cursor.file_name(), cursor.parent()) { (Some(name), Some(parent)) => { tail.push(name.to_os_string()); cursor = parent; } _ => return Err(Error::PathRejected(format!("cannot resolve {}", path.display()))), }, } } } /// Validate that `candidate` (absolute, or relative to `root`) resolves inside `root`, /// following existing symlinks/junctions. Returns the resolved path. pub fn ensure_within(root: &Path, candidate: &Path) -> Result { let root = canonicalize_lenient(root)?; let joined = if candidate.is_absolute() { candidate.to_path_buf() } else { root.join(candidate) }; let resolved = canonicalize_lenient(&joined)?; if starts_with_ci(&resolved, &root) { Ok(resolved) } else { Err(Error::PathRejected(format!("{} is outside {}", resolved.display(), root.display()))) } } /// Join an untrusted relative path (from a manifest / archive) onto `root`. /// Rejects absolute paths, drive prefixes, `..`, empty components, NTFS streams and reserved device names. pub fn safe_join(root: &Path, rel: &str) -> Result { let bad = |why: &str| Error::PathRejected(format!("{rel:?}: {why}")); if rel.is_empty() { return Err(bad("empty")); } if rel.contains(':') { return Err(bad("drive or stream marker")); } let normalized = rel.replace('\\', "/"); if normalized.starts_with('/') { return Err(bad("absolute")); } let mut out = root.to_path_buf(); for part in normalized.split('/') { match part { "" | "." => return Err(bad("empty or dot component")), ".." => return Err(bad("parent traversal")), p => { if p.ends_with('.') || p.ends_with(' ') { return Err(bad("trailing dot or space")); } let stem = p.split('.').next().unwrap_or("").to_ascii_uppercase(); const RESERVED: [&str; 22] = [ "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", ]; if RESERVED.contains(&stem.as_str()) { return Err(bad("reserved device name")); } out.push(p); } } } Ok(out) } /// Write `bytes` to `path` so readers see either the old or the new content, never a partial file. pub fn atomic_write(path: &Path, bytes: &[u8]) -> Result<()> { let parent = path.parent().ok_or_else(|| Error::PathRejected("no parent directory".into()))?; fs::create_dir_all(parent)?; let tmp = parent.join(format!( ".{}.{}.tmp", path.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default(), std::process::id() )); let write = || -> std::io::Result<()> { let mut f = OpenOptions::new().write(true).create_new(true).open(&tmp)?; f.write_all(bytes)?; f.sync_all()?; Ok(()) }; if let Err(e) = write() { let _ = fs::remove_file(&tmp); return Err(e.into()); } if let Err(e) = fs::rename(&tmp, path) { let _ = fs::remove_file(&tmp); return Err(e.into()); } Ok(()) } pub fn atomic_write_json(path: &Path, value: &T) -> Result<()> { let mut bytes = serde_json::to_vec_pretty(value)?; bytes.push(b'\n'); atomic_write(path, &bytes) } pub fn read_json(path: &Path) -> Result { let bytes = fs::read(path)?; let bytes = bytes.strip_prefix(&[0xEF, 0xBB, 0xBF][..]).unwrap_or(&bytes); Ok(serde_json::from_slice(bytes)?) } pub fn sha256_file(path: &Path) -> Result { let mut file = File::open(path)?; let mut hasher = Sha256::new(); let mut buf = vec![0u8; 1 << 20]; loop { let n = file.read(&mut buf)?; if n == 0 { break; } hasher.update(&buf[..n]); } Ok(hex::encode(hasher.finalize())) } pub fn sha256_bytes(bytes: &[u8]) -> String { hex::encode(Sha256::digest(bytes)) } /// Free bytes on the volume that holds `path` (or its nearest existing ancestor). pub fn free_space(path: &Path) -> Result { let path = std::path::absolute(path)?; let mut cursor = Some(path.as_path()); while let Some(p) = cursor { if p.exists() { return Ok(fs4::available_space(p)?); } cursor = p.parent(); } Err(Error::PathRejected(format!("no existing ancestor for {}", path.display()))) } /// Fail before writing if the volume cannot hold `needed` bytes plus a safety margin. pub fn require_space(path: &Path, needed: u64) -> Result<()> { const MARGIN: u64 = 256 * 1024 * 1024; let available = free_space(path)?; if available < needed.saturating_add(MARGIN) { return Err(Error::InsufficientSpace { needed: needed.saturating_add(MARGIN), available }); } Ok(()) } #[cfg(test)] mod tests { use super::*; #[test] fn safe_join_accepts_normal_and_rejects_traversal() { let root = Path::new("C:/srv"); assert!(safe_join(root, "Core/worldserver.exe").is_ok()); assert!(safe_join(root, "Core\\configs\\a.conf").is_ok()); for bad in ["", "../x", "a/../../x", "/abs", "C:/x", "a/./b", "a//b", "a/CON", "a/nul.txt", "x.exe:zone", "a/b.", "a/b "] { assert!(safe_join(root, bad).is_err(), "should reject {bad:?}"); } } #[test] fn ensure_within_blocks_escape() { let dir = tempfile::tempdir().unwrap(); let root = dir.path().join("srv"); fs::create_dir_all(&root).unwrap(); assert!(ensure_within(&root, Path::new("Core/new/file.txt")).is_ok()); assert!(ensure_within(&root, Path::new("../evil")).is_err()); assert!(ensure_within(&root, &dir.path().join("other")).is_err()); // case-insensitive root match (Windows) let upper = PathBuf::from(root.to_string_lossy().to_uppercase()).join("a"); if cfg!(windows) { assert!(ensure_within(&root, &upper).is_ok()); } } #[test] fn ensure_within_blocks_junction_escape() { if !cfg!(windows) { return; } let dir = tempfile::tempdir().unwrap(); let root = dir.path().join("srv"); let outside = dir.path().join("outside"); fs::create_dir_all(&root).unwrap(); fs::create_dir_all(&outside).unwrap(); let link = root.join("link"); // A directory junction needs no privileges (unlike symlinks). let status = std::process::Command::new("cmd") .args(["/C", "mklink", "/J"]) .arg(&link) .arg(&outside) .output() .unwrap(); if !status.status.success() { return; } assert!(ensure_within(&root, &link.join("file.txt")).is_err()); } #[test] fn atomic_write_replaces_and_leaves_no_temp() { let dir = tempfile::tempdir().unwrap(); let p = dir.path().join("a.json"); atomic_write(&p, b"one").unwrap(); atomic_write(&p, b"two").unwrap(); assert_eq!(fs::read(&p).unwrap(), b"two"); let leftovers: Vec<_> = fs::read_dir(dir.path()).unwrap().collect(); assert_eq!(leftovers.len(), 1); } #[test] fn sha256_matches_known_vector() { assert_eq!(sha256_bytes(b"abc"), "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"); let dir = tempfile::tempdir().unwrap(); let p = dir.path().join("f"); fs::write(&p, b"abc").unwrap(); assert_eq!(sha256_file(&p).unwrap(), sha256_bytes(b"abc")); } #[test] fn read_json_tolerates_bom() { let dir = tempfile::tempdir().unwrap(); let p = dir.path().join("b.json"); fs::write(&p, b"\xEF\xBB\xBF{\"a\":1}").unwrap(); let v: serde_json::Value = read_json(&p).unwrap(); assert_eq!(v["a"], 1); } #[test] fn require_space_rejects_absurd_request() { let dir = tempfile::tempdir().unwrap(); assert!(matches!(require_space(dir.path(), u64::MAX / 2), Err(Error::InsufficientSpace { .. }))); } #[test] fn free_space_resolves_a_new_relative_directory() { let path = Path::new("coa-schema-fixture-not-created").join("nested"); assert!(!path.exists()); assert!(free_space(&path).unwrap() > 0); } }