heddle-proto 0.3.1

An AI-native version control system
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

// SPDX-License-Identifier: Apache-2.0
//! Segment-aware scope containment for namespace-tree access checks.
//!
//! This is the single authorization primitive for "is `candidate` inside the
//! namespace tree rooted at `scope`?". Callers MUST NOT reimplement this with
//! string prefix matching: `candidate.starts_with(&format!("{}/", scope))`
//! treats `..` segments literally, so `a/b/../c` passes a check against scope
//! `a/b` and then normalizes to the *sibling* `a/c` — a check-then-normalize
//! bypass (see heddle#631).

/// Whether `candidate` is the scope namespace itself or a descendant of it,
/// compared whole-segment by whole-segment.
///
/// Hardening rules (deny-by-default):
/// - Any `.` or `..` segment in either string is rejected outright. We never
///   normalize traversal segments — a path that needs normalizing is denied.
/// - Empty segments (`a//b`, leading/trailing `/`, or the empty string) are
///   rejected outright, so `/`-boundary tricks cannot smuggle segments past
///   the comparison.
/// - Comparison is per-segment, so scope `a/b` does NOT match `a/bc` (the
///   classic non-boundary prefix bug) and never grants upward access (scope
///   `a/b` does not match `a`).
pub fn scope_contains(scope: &str, candidate: &str) -> bool {
    let Some(scope_segments) = well_formed_segments(scope) else {
        return false;
    };
    let Some(candidate_segments) = well_formed_segments(candidate) else {
        return false;
    };

    candidate_segments.len() >= scope_segments.len()
        && scope_segments == candidate_segments[..scope_segments.len()]
}

/// Splits `path` on `/`, returning `None` if any segment is empty, `.`,
/// or `..` (including the empty string itself).
fn well_formed_segments(path: &str) -> Option<Vec<&str>> {
    let segments: Vec<&str> = path.split('/').collect();
    if segments
        .iter()
        .any(|segment| segment.is_empty() || *segment == "." || *segment == "..")
    {
        return None;
    }
    Some(segments)
}

#[cfg(test)]
mod tests {
    use super::scope_contains;

    #[test]
    fn exact_match_allowed() {
        assert!(scope_contains("a/b", "a/b"));
    }

    #[test]
    fn descendant_allowed() {
        assert!(scope_contains("a/b", "a/b/c"));
        assert!(scope_contains("a/b", "a/b/c/d"));
    }

    #[test]
    fn dotdot_traversal_denied() {
        // The heddle#631 bypass: matches the old prefix check, normalizes to
        // the sibling a/c after it.
        assert!(!scope_contains("a/b", "a/b/../c"));
        assert!(!scope_contains("a/b", "a/b/.."));
        assert!(!scope_contains("a/b", "a/b/c/../../b/c"));
    }

    #[test]
    fn single_dot_denied() {
        // We deny rather than normalize: no traversal-ish input is trusted.
        assert!(!scope_contains("a/b", "a/b/./c"));
        assert!(!scope_contains("a/b", "a/b/."));
    }

    #[test]
    fn empty_segments_denied() {
        assert!(!scope_contains("a/b", "a//b"));
        assert!(!scope_contains("a/b", "a/b//c"));
        assert!(!scope_contains("a/b", "a/b/"));
        assert!(!scope_contains("a/b", "/a/b"));
        assert!(!scope_contains("a/b", ""));
    }

    #[test]
    fn sibling_denied() {
        assert!(!scope_contains("a/b", "a/c"));
    }

    #[test]
    fn upward_access_denied() {
        assert!(!scope_contains("a/b", "a"));
        assert!(!scope_contains("a/b/c", "a/b"));
    }

    #[test]
    fn non_boundary_prefix_denied() {
        // scope "a/b" must not match "a/bc" in either direction.
        assert!(!scope_contains("a/b", "a/bc"));
        assert!(!scope_contains("a/bc", "a/b"));
    }

    #[test]
    fn malformed_scope_denies_everything() {
        // A scope containing traversal/empty segments is misconfigured;
        // deny rather than guess.
        assert!(!scope_contains("a/..", "a"));
        assert!(!scope_contains("a/../b", "a/../b"));
        assert!(!scope_contains("a//b", "a/b/c"));
        assert!(!scope_contains("", "a"));
        assert!(!scope_contains("", ""));
    }
}