coding_tools/allowlist.rs
1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2026 Jonathan Shook
3
4//! The command allow-gates behind the dispatching tools.
5//!
6//! `ct-test` and `ct-each` can run another program, so each runs **only**
7//! commands on a fixed, compiled-in list. The lists are intentionally **static
8//! and immutable**: nothing a caller does at run time can extend them, so an
9//! agent driving these tools cannot grant itself new commands. A command that
10//! is not on the relevant list is refused, and nothing runs. There is no shell
11//! mode anywhere in the suite — every dispatch is a direct argv launch.
12//!
13//! * `ct-test` gates on [`BUILTIN`]: read-only commands only.
14//! * `ct-each` gates through [`is_allowed_for_each`]: [`BUILTIN`] plus
15//! `ct-test` (itself gated, so still read-only), and — only behind an
16//! explicit `--mutating` flag — the suite's own [`MUTATING_SUITE`] tools,
17//! which carry their own `--expect`/`--dry-run` safety gates.
18//!
19//! Gating is by **program name** (the file-name component of the command). It
20//! is a guard against unintended side effects, not a sandbox: it does not
21//! inspect arguments or resolve which binary a name ultimately runs.
22
23use std::path::Path;
24
25/// Commands trusted as read-only — `ct-test`'s entire, fixed allowlist.
26///
27/// Deliberately small and conservative: names whose ordinary use has no side
28/// effects. (`find` is excluded: `-delete`/`-exec` make it not read-only; the
29/// umbrella `ct` and the dispatching/mutating `ct-test`/`ct-each`/`ct-edit`/
30/// `ct-patch`/`ct-rules`/`ct-await` are excluded because they can change
31/// state or dispatch — the read-only `ct-search`, `ct-outline`, `ct-tree`,
32/// `ct-view`, and `ct-check` are included.) The crate-/module-graph checks
33/// (`deps`/`mods`) are not dispatch targets — they are built-in checks the rule
34/// layer runs in-process. There is no run-time mechanism to add to this list.
35pub const BUILTIN: &[&str] = &[
36 "cat",
37 "ct-check",
38 "ct-outline",
39 "ct-search",
40 "ct-tree",
41 "ct-view",
42 "echo",
43 "false",
44 "file",
45 "grep",
46 "head",
47 "ls",
48 "pwd",
49 "stat",
50 "tail",
51 "true",
52 "wc",
53];
54
55/// The suite's mutating tools, runnable by `ct-each` only behind its explicit
56/// `--mutating` flag. Each carries its own `--expect`/`--dry-run` gates, so a
57/// dispatched edit still has to assert its own effect before writing.
58pub const MUTATING_SUITE: &[&str] = &["ct-edit", "ct-patch"];
59
60/// The program name the gates check for a command: its file-name component,
61/// so `ls`, `/bin/ls`, and `./ls` all gate on `ls`.
62///
63/// # Examples
64///
65/// ```
66/// use coding_tools::allowlist::gated_name;
67///
68/// assert_eq!(gated_name("/bin/ls"), "ls");
69/// assert_eq!(gated_name("./parse"), "parse");
70/// ```
71pub fn gated_name(cmd: &str) -> String {
72 Path::new(cmd)
73 .file_name()
74 .map(|n| n.to_string_lossy().into_owned())
75 .filter(|n| !n.is_empty())
76 .unwrap_or_else(|| cmd.to_string())
77}
78
79/// Whether `name` is on `ct-test`'s fixed read-only allowlist.
80///
81/// # Examples
82///
83/// ```
84/// use coding_tools::allowlist::is_allowed;
85///
86/// assert!(is_allowed("grep")); // a built-in read-only command
87/// assert!(is_allowed("ct-search")); // the suite's own read-only tools
88/// assert!(!is_allowed("rm")); // not read-only, never runnable
89/// assert!(!is_allowed("sh")); // no shell, ever
90/// ```
91pub fn is_allowed(name: &str) -> bool {
92 BUILTIN.contains(&name)
93}
94
95/// Whether `name` is a permitted `ct-each` dispatch target.
96///
97/// The base set is [`BUILTIN`] plus `ct-test` (which only runs read-only
98/// commands itself, so dispatching it stays read-only). With `mutating`, the
99/// suite's [`MUTATING_SUITE`] tools are also permitted — and nothing else:
100/// arbitrary mutating commands are never runnable.
101///
102/// # Examples
103///
104/// ```
105/// use coding_tools::allowlist::is_allowed_for_each;
106///
107/// assert!(is_allowed_for_each("ct-view", false));
108/// assert!(is_allowed_for_each("ct-test", false)); // itself gated read-only
109/// assert!(!is_allowed_for_each("ct-edit", false)); // needs --mutating
110/// assert!(is_allowed_for_each("ct-edit", true));
111/// assert!(!is_allowed_for_each("rm", true)); // never, even with --mutating
112/// assert!(!is_allowed_for_each("sh", true)); // no shell, ever
113/// ```
114pub fn is_allowed_for_each(name: &str, mutating: bool) -> bool {
115 is_allowed(name) || name == "ct-test" || (mutating && MUTATING_SUITE.contains(&name))
116}
117
118#[cfg(test)]
119mod tests {
120 use super::*;
121
122 #[test]
123 fn gated_name_uses_basename() {
124 assert_eq!(gated_name("ls"), "ls");
125 assert_eq!(gated_name("/bin/ls"), "ls");
126 assert_eq!(gated_name("./parse"), "parse");
127 }
128
129 #[test]
130 fn builtins_allowed_everything_else_refused() {
131 assert!(is_allowed("grep"));
132 assert!(is_allowed("ct-search"));
133 // Not read-only, never runnable, and unextendable at run time.
134 assert!(!is_allowed("parse"));
135 assert!(!is_allowed("sh"));
136 assert!(!is_allowed("ct-edit"));
137 assert!(!is_allowed("ct-each"));
138 }
139
140 #[test]
141 fn each_gate_extends_only_to_suite_tools() {
142 assert!(is_allowed_for_each("grep", false));
143 assert!(is_allowed_for_each("ct-test", false));
144 assert!(!is_allowed_for_each("ct-each", false)); // no self-nesting
145 assert!(!is_allowed_for_each("ct-each", true));
146 assert!(!is_allowed_for_each("ct-edit", false));
147 assert!(is_allowed_for_each("ct-patch", true));
148 assert!(!is_allowed_for_each("mvn", true)); // external commands never
149 }
150}