Skip to main content

hyprstream_containedfs/
path.rs

1//! Path construction and validation utilities.
2
3use crate::error::FsError;
4use std::path::{Component, Path, PathBuf};
5
6/// Join an untrusted path to a base directory with traversal clamping.
7///
8/// Component-walk normalization:
9/// - Skips `.` components
10/// - Clamps `..` at root (never goes above base)
11/// - Strips `RootDir` and `Prefix` components
12/// - Rejects NUL bytes in the raw `&str` (checked before Path conversion)
13///
14/// Use this for **constructing** paths where `..` should be harmless (clamped).
15/// For I/O where traversal is never valid, use [`validate_relative_path`] instead.
16pub fn contained_join(base: &Path, untrusted: &str) -> Result<PathBuf, FsError> {
17    // Check for NUL bytes in raw string (before Path conversion which may strip them)
18    if untrusted.as_bytes().contains(&0) {
19        return Err(FsError::path_escape("NUL byte in path"));
20    }
21
22    let mut result = base.to_path_buf();
23
24    for component in Path::new(untrusted).components() {
25        match component {
26            Component::Normal(c) => result.push(c),
27            Component::CurDir | Component::RootDir | Component::Prefix(_) => {} // skip ".", strip absolute/prefix
28            Component::ParentDir => {
29                // Clamp at base — never go above it
30                if result != base {
31                    result.pop();
32                }
33            }
34        }
35    }
36
37    Ok(result)
38}
39
40/// Validate that a relative path doesn't contain traversal components.
41///
42/// **Rejects** (not clamps) `..` and absolute paths. Use this for I/O
43/// operations where traversal is never valid.
44///
45/// Returns the validated path as a `PathBuf` on success.
46pub fn validate_relative_path(path: &str) -> Result<PathBuf, FsError> {
47    // Check for NUL bytes
48    if path.as_bytes().contains(&0) {
49        return Err(FsError::path_escape("NUL byte in path"));
50    }
51
52    let rel = Path::new(path);
53    if rel.is_absolute() {
54        return Err(FsError::path_escape("absolute path rejected"));
55    }
56    for component in rel.components() {
57        match component {
58            Component::ParentDir => {
59                return Err(FsError::path_escape("path traversal via '..' rejected"));
60            }
61            Component::RootDir => {
62                return Err(FsError::path_escape("root dir component rejected"));
63            }
64            Component::Prefix(_) => {
65                return Err(FsError::path_escape("prefix component rejected"));
66            }
67            _ => {}
68        }
69    }
70    Ok(rel.to_path_buf())
71}
72
73/// Validate a git ref name (branch/tag) for safe use in paths.
74///
75/// Rules matching `git check-ref-format`:
76/// - No `..` anywhere
77/// - No ASCII control chars or ` ~ ^ : ? * [ \`
78/// - No leading/trailing `.` per component
79/// - No consecutive dots `..`
80/// - No `@{` sequence
81/// - No trailing `.lock`
82/// - Cannot be `@` alone
83/// - No NUL bytes
84/// - Non-empty
85pub fn validate_ref_name(name: &str) -> Result<(), FsError> {
86    if name.is_empty() {
87        return Err(FsError::path_escape("ref name cannot be empty"));
88    }
89
90    // Check for NUL bytes
91    if name.as_bytes().contains(&0) {
92        return Err(FsError::path_escape("NUL byte in ref name"));
93    }
94
95    // Cannot be "@" alone
96    if name == "@" {
97        return Err(FsError::path_escape("ref name cannot be '@' alone"));
98    }
99
100    // No ".." anywhere
101    if name.contains("..") {
102        return Err(FsError::path_escape("ref name cannot contain '..'"));
103    }
104
105    // No "@{" sequence
106    if name.contains("@{") {
107        return Err(FsError::path_escape("ref name cannot contain '@{'"));
108    }
109
110    // No trailing ".lock"
111    if name.ends_with(".lock") {
112        return Err(FsError::path_escape("ref name cannot end with '.lock'"));
113    }
114
115    // Check per-character and per-component constraints
116    for component in name.split('/') {
117        if component.is_empty() {
118            return Err(FsError::path_escape("ref name has empty component"));
119        }
120        // No leading or trailing '.' per component
121        if component.starts_with('.') || component.ends_with('.') {
122            return Err(FsError::path_escape(
123                "ref name component cannot start/end with '.'",
124            ));
125        }
126    }
127
128    // Check for forbidden characters
129    for byte in name.bytes() {
130        match byte {
131            // ASCII control characters (0x00-0x1F, 0x7F)
132            0x00..=0x1F | 0x7F => {
133                return Err(FsError::path_escape("ref name contains control character"));
134            }
135            // Forbidden special characters
136            b' ' | b'~' | b'^' | b':' | b'?' | b'*' | b'[' | b'\\' => {
137                return Err(FsError::path_escape(format!(
138                    "ref name contains forbidden character '{}'",
139                    byte as char
140                )));
141            }
142            _ => {}
143        }
144    }
145
146    Ok(())
147}
148
149#[cfg(test)]
150mod tests {
151    use super::*;
152    use std::path::Path;
153
154    // ── contained_join tests ─────────────────────────────────────────────
155
156    #[test]
157    fn test_contained_join_normal() {
158        let base = Path::new("/base");
159        assert_eq!(
160            contained_join(base, "subdir/file.txt").unwrap_or_default(),
161            PathBuf::from("/base/subdir/file.txt")
162        );
163    }
164
165    #[test]
166    fn test_contained_join_traversal_clamped() {
167        let base = Path::new("/base");
168        // ".." should be clamped at base, never escaping
169        assert_eq!(
170            contained_join(base, "../../../etc/passwd").unwrap_or_default(),
171            PathBuf::from("/base/etc/passwd")
172        );
173    }
174
175    #[test]
176    fn test_contained_join_absolute_stripped() {
177        let base = Path::new("/base");
178        assert_eq!(
179            contained_join(base, "/tmp/evil").unwrap_or_default(),
180            PathBuf::from("/base/tmp/evil")
181        );
182    }
183
184    #[test]
185    fn test_contained_join_dot_skipped() {
186        let base = Path::new("/base");
187        assert_eq!(
188            contained_join(base, "./subdir/../other").unwrap_or_default(),
189            PathBuf::from("/base/other")
190        );
191    }
192
193    #[test]
194    fn test_contained_join_nul_rejected() {
195        let base = Path::new("/base");
196        assert!(contained_join(base, "foo\0bar").is_err());
197    }
198
199    #[test]
200    fn test_contained_join_branch_with_slash() {
201        let base = Path::new("/base");
202        assert_eq!(
203            contained_join(base, "feature/my-branch").unwrap_or_default(),
204            PathBuf::from("/base/feature/my-branch")
205        );
206    }
207
208    #[test]
209    fn test_contained_join_unicode() {
210        let base = Path::new("/base");
211        assert_eq!(
212            contained_join(base, "日本語/ファイル").unwrap_or_default(),
213            PathBuf::from("/base/日本語/ファイル")
214        );
215    }
216
217    // ── validate_relative_path tests ─────────────────────────────────────
218
219    #[test]
220    fn test_validate_relative_path_clean() {
221        assert!(validate_relative_path("subdir/file.txt").is_ok());
222    }
223
224    #[test]
225    fn test_validate_relative_path_rejects_dotdot() {
226        assert!(validate_relative_path("../escape").is_err());
227        assert!(validate_relative_path("a/../b").is_err());
228    }
229
230    #[test]
231    fn test_validate_relative_path_rejects_absolute() {
232        assert!(validate_relative_path("/tmp/evil").is_err());
233    }
234
235    #[test]
236    fn test_validate_relative_path_rejects_nul() {
237        assert!(validate_relative_path("foo\0bar").is_err());
238    }
239
240    // ── validate_ref_name tests ──────────────────────────────────────────
241
242    #[test]
243    fn test_validate_ref_name_valid() {
244        assert!(validate_ref_name("main").is_ok());
245        assert!(validate_ref_name("feature/my-branch").is_ok());
246        assert!(validate_ref_name("v1.0.0").is_ok());
247        assert!(validate_ref_name("release/2024-01").is_ok());
248    }
249
250    #[test]
251    fn test_validate_ref_name_dotdot() {
252        assert!(validate_ref_name("a..b").is_err());
253    }
254
255    #[test]
256    fn test_validate_ref_name_nul() {
257        assert!(validate_ref_name("a\0b").is_err());
258    }
259
260    #[test]
261    fn test_validate_ref_name_at_brace() {
262        assert!(validate_ref_name("a@{b").is_err());
263    }
264
265    #[test]
266    fn test_validate_ref_name_lock() {
267        assert!(validate_ref_name("refs/heads/main.lock").is_err());
268    }
269
270    #[test]
271    fn test_validate_ref_name_control_chars() {
272        assert!(validate_ref_name("a\x01b").is_err());
273    }
274
275    #[test]
276    fn test_validate_ref_name_empty() {
277        assert!(validate_ref_name("").is_err());
278    }
279
280    #[test]
281    fn test_validate_ref_name_at_alone() {
282        assert!(validate_ref_name("@").is_err());
283    }
284
285    #[test]
286    fn test_validate_ref_name_leading_dot() {
287        assert!(validate_ref_name(".hidden").is_err());
288    }
289
290    #[test]
291    fn test_validate_ref_name_forbidden_chars() {
292        assert!(validate_ref_name("a~b").is_err());
293        assert!(validate_ref_name("a^b").is_err());
294        assert!(validate_ref_name("a:b").is_err());
295        assert!(validate_ref_name("a?b").is_err());
296        assert!(validate_ref_name("a*b").is_err());
297        assert!(validate_ref_name("a[b").is_err());
298        assert!(validate_ref_name("a\\b").is_err());
299        assert!(validate_ref_name("a b").is_err());
300    }
301}