aion_worker/shell/

template.rs

//! The parsed form of a declared command and its parameter substitution.
//!
//! A declared command is parsed ONCE, at registration, into a fixed argv
//! whose elements are either literal text or a named parameter reference.
//! Substitution then replaces a reference with a parameter's value **as one
//! whole argv element**.
//!
//! A parameter is written `{{name}}`, in one syntax, read the same way in
//! every quoting region. There is no second spelling and no escape, because
//! `$` carries no meaning here for an escape to protect.
//!
//! That structure is the security property, not a convenience. A parameter
//! value never re-enters a parser, so it cannot introduce a word boundary, a
//! quote, a pipe, a redirect, a `;`, or a `$(…)`. A value of `; rm -rf /` is
//! passed to the program as the single literal argument `; rm -rf /`. There is
//! no shell between the declaration and `execve`, so there is nothing for a
//! value to escape into. Splicing values into a command STRING and handing it
//! to `sh -c` would make every parameter an injection site; this crate never
//! does that.

use std::collections::BTreeMap;
use std::fmt::Write as _;

use thiserror::Error;

/// A declared command could not be parsed into an executable argv.
#[derive(Debug, Error, PartialEq, Eq)]
pub enum TemplateError {
    /// The command was empty or contained only whitespace, so it names no
    /// program to run.
    #[error("the declared command is empty; an action body must name a program to run")]
    Empty,
    /// A quote was opened and never closed.
    #[error("the declared command has an unterminated {quote} quote")]
    UnterminatedQuote {
        /// The quote character that was opened and never closed.
        quote: char,
    },
    /// A `{{}}` interpolated nothing.
    #[error("`{{{{}}}}` interpolates nothing; write `{{{{name}}}}` around one declared parameter")]
    EmptyParameterName,
    /// A `{{` was opened and never closed.
    #[error("`{{{{` is missing its closing `}}}}` in the declared command")]
    UnterminatedParameterBrace,
    /// The command's program name is itself a parameter reference.
    ///
    /// Refused because it would let a caller-supplied value choose which
    /// program executes.
    #[error(
        "the program to run must be a literal, not the parameter `{parameter}`; \
         a caller-supplied value must never choose which program executes"
    )]
    ParameterizedProgram {
        /// The parameter that was found in program position.
        parameter: String,
    },
}

/// A value supplied for a parameter could not be rendered into an argument.
#[derive(Debug, Error, PartialEq, Eq)]
pub enum SubstitutionError {
    /// The command references a parameter that the call did not supply.
    #[error("the declared command references parameter `{parameter}`, which was not supplied")]
    MissingParameter {
        /// The referenced parameter name.
        parameter: String,
    },
    /// A supplied value has no single unambiguous argument form.
    #[error(
        "parameter `{parameter}` is {kind}, which has no unambiguous command-argument form; \
         supply a string, number, or boolean"
    )]
    UnrepresentableValue {
        /// The referenced parameter name.
        parameter: String,
        /// The JSON kind that was supplied.
        kind: &'static str,
    },
    /// A supplied value contains a NUL byte.
    ///
    /// Refused rather than truncated: an argument is delivered to the kernel
    /// as a NUL-terminated string, so a NUL inside a value would silently cut
    /// the argument short and change what the program receives.
    #[error(
        "parameter `{parameter}` contains a NUL byte, which cannot appear in a command argument"
    )]
    InteriorNul {
        /// The referenced parameter name.
        parameter: String,
    },
}

/// One piece of a single argv element.
#[derive(Debug, Clone, PartialEq, Eq)]
enum Piece {
    /// Literal text, used exactly as written.
    Literal(String),
    /// A parameter reference, replaced by that parameter's value.
    Parameter(String),
}

/// One argv element: its pieces are concatenated to produce exactly one
/// argument, however many parameters it references.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Word {
    pieces: Vec<Piece>,
}

impl Word {
    /// Whether this word is a single bare parameter reference.
    fn sole_parameter(&self) -> Option<&str> {
        match self.pieces.as_slice() {
            [Piece::Parameter(name)] => Some(name),
            _ => None,
        }
    }

    /// Render this word into one argument using `values`.
    fn render(
        &self,
        values: &BTreeMap<String, serde_json::Value>,
    ) -> Result<String, SubstitutionError> {
        let mut rendered = String::new();
        for piece in &self.pieces {
            match piece {
                Piece::Literal(text) => rendered.push_str(text),
                Piece::Parameter(name) => {
                    let value =
                        values
                            .get(name)
                            .ok_or_else(|| SubstitutionError::MissingParameter {
                                parameter: name.clone(),
                            })?;
                    render_value(name, value, &mut rendered)?;
                }
            }
        }
        Ok(rendered)
    }
}

/// Append `value`'s argument form to `out`, refusing anything ambiguous.
fn render_value(
    parameter: &str,
    value: &serde_json::Value,
    out: &mut String,
) -> Result<(), SubstitutionError> {
    let unrepresentable = |kind: &'static str| SubstitutionError::UnrepresentableValue {
        parameter: parameter.to_owned(),
        kind,
    };
    match value {
        serde_json::Value::String(text) => {
            if text.contains('\0') {
                return Err(SubstitutionError::InteriorNul {
                    parameter: parameter.to_owned(),
                });
            }
            out.push_str(text);
            Ok(())
        }
        serde_json::Value::Number(number) => {
            // `write!` to a String is infallible; the result is consumed so no
            // formatting error can be silently dropped.
            let _ = write!(out, "{number}");
            Ok(())
        }
        serde_json::Value::Bool(flag) => {
            out.push_str(if *flag { "true" } else { "false" });
            Ok(())
        }
        // A null, array, or object has no single obvious argument spelling.
        // Guessing one (empty string? JSON text? space-joined?) would make the
        // command mean something the author never wrote, so each is refused by
        // name instead.
        serde_json::Value::Null => Err(unrepresentable("null")),
        serde_json::Value::Array(_) => Err(unrepresentable("an array")),
        serde_json::Value::Object(_) => Err(unrepresentable("an object")),
    }
}

/// A declared command parsed into an executable argv with named holes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommandTemplate {
    program: Word,
    arguments: Vec<Word>,
}

impl CommandTemplate {
    /// Parse a declared command into a program and its arguments.
    ///
    /// Words are split on unquoted whitespace. Single and double quotes both
    /// group text into one word. A parameter is written `{{name}}`, and it is
    /// read in EVERY region — a quote groups, it never changes what an
    /// interpolation means. `$` is an ordinary character with no meaning of
    /// its own.
    ///
    /// # Errors
    ///
    /// Returns [`TemplateError`] when the command is empty, a quote or `{{`
    /// is unterminated, an interpolation names nothing, or the program
    /// position is a parameter reference.
    pub fn parse(command: &str) -> Result<Self, TemplateError> {
        let mut words = Vec::new();
        let mut pieces: Vec<Piece> = Vec::new();
        let mut literal = String::new();
        let mut started = false;
        let mut chars = command.char_indices().peekable();

        // Close the literal run in progress, if any, into `pieces`.
        macro_rules! flush_literal {
            () => {
                if !literal.is_empty() {
                    pieces.push(Piece::Literal(std::mem::take(&mut literal)));
                }
            };
        }

        // Which quote, if any, is open. A quote decides word GROUPING and
        // nothing else: an interpolation means the same thing inside one as
        // outside, which is what removes the trap where `\'{{x}}\'` and
        // `"{{x}}"` looked alike and meant different things.
        let mut quote: Option<char> = None;

        while let Some(&(index, character)) = chars.peek() {
            if command[index..].starts_with(HOLE_OPEN) {
                started = true;
                flush_literal!();
                push_parameter(&mut chars, command, index, &mut pieces)?;
                continue;
            }
            chars.next();
            match character {
                _ if quote.is_none() && character.is_whitespace() => {
                    flush_literal!();
                    if started {
                        words.push(Word {
                            pieces: std::mem::take(&mut pieces),
                        });
                        started = false;
                    }
                }
                '\'' | '"' => {
                    started = true;
                    match quote {
                        None => quote = Some(character),
                        Some(open) if open == character => quote = None,
                        Some(_) => literal.push(character),
                    }
                }
                other => {
                    started = true;
                    literal.push(other);
                }
            }
        }

        if let Some(open) = quote {
            return Err(TemplateError::UnterminatedQuote { quote: open });
        }

        flush_literal!();
        if started {
            words.push(Word { pieces });
        }

        let mut words = words.into_iter();
        let program = words.next().ok_or(TemplateError::Empty)?;
        if let Some(parameter) = program.sole_parameter() {
            return Err(TemplateError::ParameterizedProgram {
                parameter: parameter.to_owned(),
            });
        }
        Ok(Self {
            program,
            arguments: words.collect(),
        })
    }

    /// The parameter names this command references, in sorted order.
    #[must_use]
    pub fn referenced_parameters(&self) -> Vec<String> {
        let mut names: Vec<String> = std::iter::once(&self.program)
            .chain(&self.arguments)
            .flat_map(|word| &word.pieces)
            .filter_map(|piece| match piece {
                Piece::Parameter(name) => Some(name.clone()),
                Piece::Literal(_) => None,
            })
            .collect();
        names.sort_unstable();
        names.dedup();
        names
    }

    /// Render the full argv, substituting `values` for parameter references.
    ///
    /// The first element is the program; the rest are its arguments. Each
    /// element is one whole argument regardless of what a value contains.
    ///
    /// # Errors
    ///
    /// Returns [`SubstitutionError`] when a referenced parameter is absent or
    /// its value has no unambiguous argument form.
    pub fn render(
        &self,
        values: &BTreeMap<String, serde_json::Value>,
    ) -> Result<Vec<String>, SubstitutionError> {
        let mut argv = Vec::with_capacity(self.arguments.len() + 1);
        argv.push(self.program.render(values)?);
        for argument in &self.arguments {
            argv.push(argument.render(values)?);
        }
        Ok(argv)
    }
}

/// The opening delimiter of an interpolation.
const HOLE_OPEN: &str = "{{";
/// The closing delimiter of an interpolation.
const HOLE_CLOSE: &str = "}}";

/// Consume a `{{name}}` interpolation. The cursor stands on the `{{`.
fn push_parameter(
    chars: &mut std::iter::Peekable<std::str::CharIndices<'_>>,
    command: &str,
    open: usize,
    pieces: &mut Vec<Piece>,
) -> Result<(), TemplateError> {
    let after_open = &command[open + HOLE_OPEN.len()..];
    let Some(close) = after_open.find(HOLE_CLOSE) else {
        return Err(TemplateError::UnterminatedParameterBrace);
    };
    let end = open + HOLE_OPEN.len() + close + HOLE_CLOSE.len();
    while matches!(chars.peek(), Some(&(index, _)) if index < end) {
        chars.next();
    }
    let name = after_open[..close].trim();
    if name.is_empty() {
        return Err(TemplateError::EmptyParameterName);
    }
    pieces.push(Piece::Parameter(name.to_owned()));
    Ok(())
}

#[cfg(test)]
mod tests {
    //! `{{name}}` is the one interpolation this executor knows, and these pin
    //! that it means the same thing in every quoting region. `$` carries no
    //! meaning at all on this side — the compiler only ever hands the executor
    //! the canonical spelling, so a `$` that reaches here is a literal `$` the
    //! author wrote and nothing else.

    use super::{CommandTemplate, SubstitutionError, TemplateError};
    use std::collections::BTreeMap;

    fn values(pairs: &[(&str, serde_json::Value)]) -> BTreeMap<String, serde_json::Value> {
        pairs
            .iter()
            .map(|(name, value)| ((*name).to_owned(), value.clone()))
            .collect()
    }

    /// What a test returns. Every fallible step is carried rather than
    /// unwrapped, because the workspace denies panicking accessors in test
    /// code as firmly as in library code.
    type TestResult = Result<(), Box<dyn std::error::Error>>;

    fn render(
        command: &str,
        pairs: &[(&str, serde_json::Value)],
    ) -> Result<Vec<String>, Box<dyn std::error::Error>> {
        Ok(CommandTemplate::parse(command)?.render(&values(pairs))?)
    }

    #[test]
    fn splits_a_plain_command_into_program_and_arguments() -> TestResult {
        assert_eq!(render("echo hello world", &[])?, ["echo", "hello", "world"]);
        Ok(())
    }

    #[test]
    fn collapses_runs_of_whitespace_between_words() -> TestResult {
        assert_eq!(render("echo   a\t\tb", &[])?, ["echo", "a", "b"]);
        Ok(())
    }

    #[test]
    fn substitutes_a_bare_parameter_as_one_argument() -> TestResult {
        assert_eq!(
            render("echo {{name}}", &[("name", serde_json::json!("Ada"))])?,
            ["echo", "Ada"]
        );
        Ok(())
    }

    #[test]
    fn a_parameter_abutting_more_text_makes_one_word() -> TestResult {
        assert_eq!(
            render("echo {{name}}!", &[("name", serde_json::json!("Ada"))])?,
            ["echo", "Ada!"]
        );
        Ok(())
    }

    #[test]
    fn padding_inside_the_braces_is_not_part_of_the_name() -> TestResult {
        assert_eq!(
            render("echo {{ name }}", &[("name", serde_json::json!("Ada"))])?,
            ["echo", "Ada"]
        );
        Ok(())
    }

    #[test]
    fn a_value_containing_spaces_stays_one_argument() -> TestResult {
        // The whole point: no word splitting after substitution.
        assert_eq!(
            render(
                "echo {{name}}",
                &[("name", serde_json::json!("Ada Lovelace"))]
            )?,
            ["echo", "Ada Lovelace"]
        );
        Ok(())
    }

    #[test]
    fn shell_metacharacters_in_a_value_are_inert_literal_text() -> TestResult {
        // A value can never introduce a command, a pipe, or a redirect: it is
        // handed to the program as one argument and never re-parsed.
        for hostile in [
            "; rm -rf /",
            "$(rm -rf /)",
            "`rm -rf /`",
            "a | b",
            "a && b",
            "a > /etc/passwd",
            "'; DROP TABLE users; --",
            "$HOME",
            "\n rm -rf /",
        ] {
            assert_eq!(
                render("echo {{value}}", &[("value", serde_json::json!(hostile))])?,
                ["echo", hostile],
                "a value must never be re-parsed: {hostile}"
            );
        }
        Ok(())
    }

    #[test]
    fn a_substituted_value_is_never_rescanned_for_parameters() -> TestResult {
        assert_eq!(
            render(
                "echo {{outer}}",
                &[
                    ("outer", serde_json::json!("{{inner}}")),
                    ("inner", serde_json::json!("substituted twice")),
                ]
            )?,
            ["echo", "{{inner}}"]
        );
        Ok(())
    }

    #[test]
    fn double_quotes_group_text_and_still_substitute() -> TestResult {
        assert_eq!(
            render(
                "echo \"hello {{name}}\"",
                &[("name", serde_json::json!("Ada"))]
            )?,
            ["echo", "hello Ada"]
        );
        Ok(())
    }

    #[test]
    fn single_quotes_group_text_and_still_substitute() -> TestResult {
        // THE TRAP THAT IS GONE. `'…'` used to be literal for the retired `$`
        // spelling while `"…"` substituted, the two looked identical in an
        // editor, and getting it backwards produced a vacuous success rather
        // than a failure. A quote groups; it never decides what an
        // interpolation means.
        assert_eq!(
            render(
                "sh -c 'echo {{name}}'",
                &[("name", serde_json::json!("Ada"))]
            )?,
            ["sh", "-c", "echo Ada"]
        );
        Ok(())
    }

    #[test]
    fn a_dollar_sign_is_ordinary_literal_text_in_every_region() -> TestResult {
        // There is no shell here and no second spelling, so nothing on this
        // side reads a `$`: it reaches the program exactly as written,
        // quoted or not.
        assert_eq!(
            render(
                "echo $HOME '$1' $$ {{name}}",
                &[("name", serde_json::json!("Ada"))]
            )?,
            ["echo", "$HOME", "$1", "$$", "Ada"]
        );
        Ok(())
    }

    #[test]
    fn a_single_brace_is_ordinary_literal_text() -> TestResult {
        // Only the doubled brace opens an interpolation, so an `awk` program
        // or a shell brace expansion passes through untouched.
        assert_eq!(
            render(
                "awk {print $1} {{path}}",
                &[("path", serde_json::json!("/tmp/x"))]
            )?,
            ["awk", "{print", "$1}", "/tmp/x"]
        );
        Ok(())
    }

    #[test]
    fn an_empty_quoted_word_survives_as_an_empty_argument() -> TestResult {
        assert_eq!(render("echo '' x", &[])?, ["echo", "", "x"]);
        Ok(())
    }

    #[test]
    fn numbers_and_booleans_render_without_quotes() -> TestResult {
        assert_eq!(
            render(
                "run {{count}} {{flag}}",
                &[
                    ("count", serde_json::json!(42)),
                    ("flag", serde_json::json!(true)),
                ]
            )?,
            ["run", "42", "true"]
        );
        Ok(())
    }

    #[test]
    fn an_empty_command_is_refused() {
        assert_eq!(CommandTemplate::parse("   "), Err(TemplateError::Empty));
    }

    #[test]
    fn an_unterminated_quote_is_refused() {
        assert_eq!(
            CommandTemplate::parse("echo 'oops"),
            Err(TemplateError::UnterminatedQuote { quote: '\'' })
        );
        assert_eq!(
            CommandTemplate::parse("echo \"oops"),
            Err(TemplateError::UnterminatedQuote { quote: '"' })
        );
    }

    #[test]
    fn an_unterminated_interpolation_is_refused() {
        assert_eq!(
            CommandTemplate::parse("echo {{name"),
            Err(TemplateError::UnterminatedParameterBrace)
        );
    }

    #[test]
    fn an_interpolation_naming_nothing_is_refused() {
        assert_eq!(
            CommandTemplate::parse("echo {{}}"),
            Err(TemplateError::EmptyParameterName)
        );
        assert_eq!(
            CommandTemplate::parse("echo {{   }}"),
            Err(TemplateError::EmptyParameterName)
        );
    }

    #[test]
    fn a_parameterized_program_is_refused() {
        // A caller-supplied value must never choose which program runs.
        assert_eq!(
            CommandTemplate::parse("{{program}} arg"),
            Err(TemplateError::ParameterizedProgram {
                parameter: "program".to_owned()
            })
        );
    }

    #[test]
    fn a_missing_parameter_is_refused_by_name() -> TestResult {
        let Err(error) = CommandTemplate::parse("echo {{absent}}")?.render(&BTreeMap::new()) else {
            return Err("a missing parameter must be refused, not rendered".into());
        };
        assert_eq!(
            error,
            SubstitutionError::MissingParameter {
                parameter: "absent".to_owned()
            }
        );
        Ok(())
    }

    #[test]
    fn structured_and_null_values_are_refused_rather_than_guessed() -> TestResult {
        for (value, kind) in [
            (serde_json::json!(null), "null"),
            (serde_json::json!([1, 2]), "an array"),
            (serde_json::json!({"a": 1}), "an object"),
        ] {
            let Err(error) =
                CommandTemplate::parse("echo {{value}}")?.render(&values(&[("value", value)]))
            else {
                return Err(format!("a value that is {kind} must be refused, not guessed").into());
            };
            assert_eq!(
                error,
                SubstitutionError::UnrepresentableValue {
                    parameter: "value".to_owned(),
                    kind
                }
            );
        }
        Ok(())
    }

    #[test]
    fn an_interior_nul_is_refused_rather_than_truncating_the_argument() -> TestResult {
        let Err(error) = CommandTemplate::parse("echo {{value}}")?
            .render(&values(&[("value", serde_json::json!("a\0b"))]))
        else {
            return Err("an interior NUL must be refused, not silently truncated".into());
        };
        assert_eq!(
            error,
            SubstitutionError::InteriorNul {
                parameter: "value".to_owned()
            }
        );
        Ok(())
    }

    #[test]
    fn referenced_parameters_are_reported_sorted_and_deduplicated() -> TestResult {
        let template = CommandTemplate::parse("run {{b}} {{a}} {{b}} literal")?;
        assert_eq!(template.referenced_parameters(), ["a", "b"]);
        Ok(())
    }
}