//! 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| { #[cfg(windows)] if let Component::Prefix(prefix) = c { use std::path::Prefix; match prefix.kind() { Prefix::Disk(drive) | Prefix::VerbatimDisk(drive) => { return format!("{}:", char::from(drive).to_ascii_lowercase()); } Prefix::UNC(server, share) | Prefix::VerbatimUNC(server, share) => { return format!("\\\\{}\\{}", server.to_string_lossy(), share.to_string_lossy()).to_lowercase(); } _ => {} } } 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(), uuid::Uuid::new_v4().simple() )); 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) = durable_replace(&tmp, path) { let _ = fs::remove_file(&tmp); return Err(e.into()); } Ok(()) } /// The temporary file must already be flushed, on the same volume as the destination. pub(crate) fn durable_replace(from: &Path, to: &Path) -> std::io::Result<()> { #[cfg(windows)] { use std::os::windows::ffi::OsStrExt; use windows_sys::Win32::Storage::FileSystem::{MoveFileExW, MOVEFILE_REPLACE_EXISTING, MOVEFILE_WRITE_THROUGH}; fn wide(path: &Path) -> std::io::Result> { let absolute = std::path::absolute(path)?; let text = absolute.as_os_str().to_string_lossy().replace('/', "\\"); let extended = if text.starts_with("\\\\?\\") { text } else if let Some(unc) = text.strip_prefix("\\\\") { format!("\\\\?\\UNC\\{unc}") } else { format!("\\\\?\\{text}") }; Ok(std::ffi::OsStr::new(&extended).encode_wide().chain(Some(0)).collect()) } let src = wide(from)?; let dst = wide(to)?; if unsafe { MoveFileExW(src.as_ptr(), dst.as_ptr(), MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) } == 0 { return Err(std::io::Error::last_os_error()); } Ok(()) } #[cfg(not(windows))] { fs::rename(from, to)?; File::open(to.parent().unwrap())?.sync_all() } } 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 durable_replacement_handles_long_transaction_backup_paths() { let dir = tempfile::tempdir().unwrap(); let parent = dir.path().join("a".repeat(90)).join("b".repeat(90)); let path = parent.join("configuration-with-a-long-name.template"); atomic_write(&path, b"old").unwrap(); atomic_write(&path, b"new").unwrap(); assert_eq!(fs::read(&path).unwrap(), b"new"); } #[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()); } } #[cfg(windows)] #[test] fn containment_matches_verbatim_drive_and_unc_prefixes() { assert!(starts_with_ci(Path::new(r"\\?\C:\server\Extras\file.sql"), Path::new(r"C:\server"))); assert!(starts_with_ci(Path::new(r"C:\server\Extras\file.sql"), Path::new(r"\\?\c:\server"))); assert!(starts_with_ci(Path::new(r"\\?\UNC\host\share\server\file.sql"), Path::new(r"\\host\share\server"))); assert!(!starts_with_ci(Path::new(r"\\?\D:\server\file.sql"), Path::new(r"C:\server"))); assert!(!starts_with_ci(Path::new(r"\\?\C:\server-other\file.sql"), Path::new(r"C:\server"))); assert!(!starts_with_ci(Path::new(r"\\?\UNC\host\other\server\file.sql"), Path::new(r"\\host\share\server"))); } #[cfg(windows)] #[test] fn ensure_within_accepts_long_rehearsal_sql_path() { let dir = tempfile::tempdir().unwrap(); let root = dir.path().join("server"); fs::create_dir_all(&root).unwrap(); let mut candidate = root.clone(); for _ in 0..5 { candidate.push("long-private-rehearsal-directory-name-20261013"); } fs::create_dir_all(&candidate).unwrap(); candidate.push("2026_06_13_00_ai_playerbot_missing_group_buff_reagent.sql"); fs::write(&candidate, b"SELECT 1;").unwrap(); assert!(candidate.as_os_str().len() > 260); assert!(ensure_within(&root, &candidate).is_ok()); assert!(ensure_within(&root, &std::fs::canonicalize(candidate).unwrap()).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); } }