runx-core 0.6.19

Pure Rust parity kernel for runx state-machine and policy decisions.
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

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ToolRefAdmission {
    pub allowed: bool,
    pub reason: &'static str,
}

impl ToolRefAdmission {
    #[must_use]
    pub const fn allow() -> Self {
        Self {
            allowed: true,
            reason: "tool ref admitted",
        }
    }

    #[must_use]
    pub const fn deny(reason: &'static str) -> Self {
        Self {
            allowed: false,
            reason,
        }
    }
}

#[must_use]
pub fn admit_agent_tool_ref(value: &str) -> ToolRefAdmission {
    let value = value.trim();
    if value.is_empty() {
        return ToolRefAdmission::deny("tool ref must not be empty");
    }
    if value.starts_with('/') || value.starts_with('\\') {
        return ToolRefAdmission::deny("tool ref must not be an absolute path");
    }
    if value.contains('/') || value.contains('\\') || value.contains("..") {
        return ToolRefAdmission::deny("tool ref must not contain path traversal or separators");
    }
    let lower = value.to_ascii_lowercase();
    if lower == "manifest.json"
        || lower.ends_with(".json")
        || lower.ends_with(".yaml")
        || lower.ends_with(".yml")
        || lower.ends_with(".toml")
    {
        return ToolRefAdmission::deny("tool ref must not look like a manifest or data file path");
    }
    let segments = value.split('.').collect::<Vec<_>>();
    if segments.len() < 2 {
        return ToolRefAdmission::deny("tool ref must include a namespace, for example fs.read");
    }
    if segments
        .iter()
        .any(|segment| segment.is_empty() || !segment.bytes().all(is_catalog_ref_byte))
    {
        return ToolRefAdmission::deny(
            "tool ref segments must contain only letters, numbers, hyphens, or underscores",
        );
    }
    ToolRefAdmission::allow()
}

const fn is_catalog_ref_byte(byte: u8) -> bool {
    byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_'
}

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

    #[test]
    fn admits_catalog_style_refs() {
        for value in [
            "fs.read",
            "git.current_branch",
            "git.diff_name_only",
            "shell.exec",
            "cli.capture_help",
            "namespace.tool-name",
        ] {
            let admission = admit_agent_tool_ref(value);
            assert!(admission.allowed, "{value}: {}", admission.reason);
        }
    }

    #[test]
    fn rejects_path_and_manifest_like_refs() {
        for value in [
            "",
            "read",
            "/tmp/tool/manifest.json",
            "../tool/manifest.json",
            "tools/read",
            r"tools\read",
            "manifest.json",
            "fs.json",
            "fs..read",
            "fs.read;rm",
            "fs.read all",
        ] {
            let admission = admit_agent_tool_ref(value);
            assert!(!admission.allowed, "{value} unexpectedly admitted");
        }
    }
}