sysknife_daemon/

executor.rs

use crate::actions::{
    apparmor, apt, apt_preferences, auditd, certbot, cloudinit, containers, deployment, distrobox,
    fail2ban, filesystem, flatpak, grub, identity, journald, layering, livepatch, logging, lvm,
    mounts, multipass, netplan, network, package_repos, pam, ppa, processes, reboot,
    release_upgrade, resolvectl, services, snap, ssh, sudoers, sysctl, system_info, toolbox,
    ubuntu_pro, ufw, users,
    validate::{
        shell_equivalent_sudo_command, validated_activatable_unit, validated_apparmor_profile,
        validated_apt_package, validated_apt_pin_expr, validated_apt_pin_name,
        validated_apt_show_package, validated_audit_path, validated_audit_perms,
        validated_cpu_quota, validated_domain, validated_email, validated_fstype, validated_group,
        validated_group_not_critical, validated_home_dir, validated_hostname,
        validated_install_package, validated_journal_grep, validated_journal_priority,
        validated_journal_time, validated_locale, validated_log_path, validated_log_rotation,
        validated_lvm_name, validated_lvm_size, validated_memory_limit, validated_mount_device,
        validated_mount_options, validated_mount_point, validated_port_or_service,
        validated_ppa_name, validated_pro_service, validated_rebase_ref,
        validated_resource_limit_unit, validated_safe_arg, validated_stoppable_unit,
        validated_sudo_commands, validated_sudoers_name, validated_swap_path, validated_sysctl_key,
        validated_sysctl_value, validated_syslog_host, validated_tasks_max, validated_timezone,
        validated_unit_name, validated_unmodified_package, validated_username,
        validated_username_not_critical,
    },
    ActionMechanism, ActionSpec,
};
use async_trait::async_trait;
use serde_json::Value;
use std::io;
use std::net::IpAddr;
use std::process::Stdio;
use std::str::FromStr;
use std::time::Duration;
use tokio::io::{AsyncBufReadExt, AsyncReadExt, BufReader};
use tokio::sync::mpsc::UnboundedSender;

// ---------------------------------------------------------------------------
// Parameter bounds
// ---------------------------------------------------------------------------
//
// These mirror the ceilings of the tools being driven (`chage`, `faillock`,
// `pam_pwquality`, `fail2ban`, `journalctl`, `mkswap`). Naming them keeps the
// rejection reason legible and keeps the same tool's ceiling from being spelled
// two different ways in two arms of the same match.

/// Longest scheduled-job command line.
const MAX_SCHEDULED_COMMAND_LEN: usize = 512;
/// Longest schedule expression (`OnCalendar=` / cron form).
const MAX_SCHEDULE_EXPR_LEN: usize = 128;
/// Widest `journalctl --lines` request. Values are clamped, not rejected: an
/// over-large request is a preference, not an error.
const MAX_JOURNAL_LINES: u64 = 10_000;
/// Largest swap file, in MiB (1 TiB).
const MAX_SWAP_SIZE_MB: u32 = 1_048_576;
/// `chage`'s own ceiling for password-age days.
const MAX_PASSWORD_AGE_DAYS: u64 = 99_999;
/// Widest `pam_pwquality` minimum length.
const MAX_PASSWORD_MINLEN: u64 = 128;
/// Longest `faillock` unlock/interval window, in seconds (7 days).
const MAX_LOCKOUT_WINDOW_SECS: u64 = 604_800;
/// Longest fail2ban bantime/findtime, in seconds (30 days).
const MAX_FAIL2BAN_WINDOW_SECS: u64 = 2_592_000;

#[derive(Debug, thiserror::Error)]
pub enum ExecutorError {
    #[error("unknown action: {0}")]
    UnknownAction(String),

    #[error("missing required param: {0}")]
    MissingParam(&'static str),

    #[error("invalid param type for: {0}")]
    InvalidParam(&'static str),

    /// Richer variant that carries the offending value for actionable diagnostics.
    ///
    /// Used when an action constructor returns a typed `InvalidIpAddress` error —
    /// the value is forwarded to user-facing output rather than being silently
    /// discarded as in the generic `InvalidParam` path.
    #[error("invalid IP address for param '{param}': '{value}'")]
    InvalidIpAddress { param: &'static str, value: String },

    #[error("io error: {0}")]
    Io(#[from] io::Error),

    /// The action outran its deadline and could not be confirmed stopped.
    ///
    /// Separate from a plain timeout because the safe response differs. A
    /// timeout that stopped the work leaves the host where it was, so an
    /// automatic rollback is reasonable. This variant means privileged work may
    /// still be running, and rolling back over it would put two package
    /// transactions on the host at once. The caller must not treat it as a
    /// quiet failure.
    #[error(
        "{program} exceeded the {timeout_secs}s action timeout and could not be \
         confirmed stopped: process group {pgid} still has members. Automatic \
         rollback was skipped because the original action may still be running; \
         inspect the host before retrying"
    )]
    ActionNotStopped {
        program: String,
        pgid: i32,
        timeout_secs: u64,
    },
}

/// Output of a single executed action.
///
/// `exit_code` is the discriminant between success and failure.  Prefer
/// [`is_success`](Self::is_success) / [`is_nonzero`](Self::is_nonzero) at
/// call sites — `if output.exit_code == 0` is harder to read and easier to
/// invert by accident than `if output.is_success()`.  The raw `exit_code`
/// stays public because the dispatcher echoes it back to callers and the
/// rollback path includes the precise code in diagnostic messages.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ExecutionOutput {
    pub stdout: String,
    pub stderr: String,
    pub exit_code: i32,
}

impl ExecutionOutput {
    /// `true` when the action exited cleanly (`exit_code == 0`).
    pub fn is_success(&self) -> bool {
        self.exit_code == 0
    }

    /// `true` when the action failed (`exit_code != 0`).
    pub fn is_nonzero(&self) -> bool {
        self.exit_code != 0
    }
}

/// Abstraction over action execution, making the execute + rollback path
/// testable without spawning real OS commands.
///
/// The production implementation (`RealActionExecutor`) delegates to
/// `tokio::process::Command`. Tests can inject a mock that controls exit
/// codes and output per program.
#[async_trait]
pub trait ActionExecutor: Send + Sync {
    /// Execute an [`ActionSpec`] and return its output.
    async fn execute(&self, spec: &ActionSpec) -> Result<ExecutionOutput, ExecutorError>;

    /// Execute an action and publish stdout lines while it runs.
    ///
    /// Test doubles normally implement only [`execute`](Self::execute); this
    /// default forwards their captured output after completion. Production
    /// overrides the method so command output remains live.
    async fn execute_with_progress(
        &self,
        spec: &ActionSpec,
        progress: UnboundedSender<String>,
    ) -> Result<ExecutionOutput, ExecutorError> {
        let output = self.execute(spec).await?;
        for line in output.stdout.lines().filter(|line| !line.is_empty()) {
            let _ = progress.send(line.to_string());
        }
        Ok(output)
    }
}

/// Production executor that delegates to real OS processes and filesystem ops.
pub struct RealActionExecutor;

#[async_trait]
impl ActionExecutor for RealActionExecutor {
    async fn execute(&self, spec: &ActionSpec) -> Result<ExecutionOutput, ExecutorError> {
        execute_spec(spec).await
    }

    async fn execute_with_progress(
        &self,
        spec: &ActionSpec,
        progress: UnboundedSender<String>,
    ) -> Result<ExecutionOutput, ExecutorError> {
        match &spec.mechanism {
            ActionMechanism::Command { program, args } => {
                execute_command_with_progress(program, args, progress).await
            }
            _ => execute_spec(spec).await,
        }
    }
}

/// Wall-clock ceiling on a single privileged action.
///
/// Nothing else bounds these processes: without a deadline a child that never
/// exits — `apt-get` waiting on a dead mirror, a helper blocked on a prompt
/// that will never arrive — wedges its connection forever, and the exclusion
/// lock it holds is never released, so every other action contending for that
/// resource is refused from then on.
///
/// The ceiling is deliberately generous rather than tight. A release upgrade
/// or an OSTree rebase legitimately runs for tens of minutes, and killing a
/// half-finished package transaction is worse than waiting. This is a
/// backstop against a hang, not a performance budget. Override with
/// `SYSKNIFE_ACTION_TIMEOUT_SECS` when an action on a slow link needs longer.
const DEFAULT_ACTION_TIMEOUT: Duration = Duration::from_secs(2 * 60 * 60);

fn action_timeout() -> Duration {
    match std::env::var("SYSKNIFE_ACTION_TIMEOUT_SECS") {
        Ok(raw) => match raw.trim().parse::<u64>() {
            Ok(secs) if secs > 0 => Duration::from_secs(secs),
            _ => {
                eprintln!(
                    "[sysknife-daemon] WARNING: ignoring invalid \
                     SYSKNIFE_ACTION_TIMEOUT_SECS={raw:?}; using the default"
                );
                DEFAULT_ACTION_TIMEOUT
            }
        },
        Err(_) => DEFAULT_ACTION_TIMEOUT,
    }
}

/// What a `killpg` probe says about a process group.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum GroupState {
    /// `ESRCH`: no process holds this group id. Gone.
    Gone,
    /// The group has members this process could signal.
    AliveReachable,
    /// `EPERM`: the group has members, but they run as a user this process
    /// cannot signal. On an unprivileged daemon that is the normal state of a
    /// `sudo` child still running as root, so it counts as *alive*, not gone.
    /// Reading it as gone was the bug that let the rollback fire over live work.
    AliveUnreachable,
    /// Any other errno. Treated as alive, because the safe default when the
    /// kernel will not answer is "still running", not "stopped".
    Unknown(i32),
}

impl GroupState {
    fn is_gone(self) -> bool {
        matches!(self, GroupState::Gone)
    }
}

/// Probe a process group without delivering a signal (`signal 0`).
fn probe_group(pgid: i32) -> GroupState {
    // SAFETY: `killpg` is async-signal-safe and takes no pointers. `pgid` is a
    // real group id from `child.id()` for a child spawned with
    // `process_group(0)`, so it is >= 1 and names that child's own group, never
    // 0 (which would address the daemon's own group).
    let rc = unsafe { libc::killpg(pgid, 0) };
    if rc == 0 {
        return GroupState::AliveReachable;
    }
    match io::Error::last_os_error().raw_os_error() {
        Some(libc::ESRCH) => GroupState::Gone,
        Some(libc::EPERM) => GroupState::AliveUnreachable,
        other => GroupState::Unknown(other.unwrap_or(0)),
    }
}

/// Send a signal to a process group. `ESRCH` is success (already gone).
fn signal_group(pgid: i32, signal: i32) -> Result<(), io::Error> {
    // SAFETY: see `probe_group`; same `pgid` contract.
    let rc = unsafe { libc::killpg(pgid, signal) };
    if rc == 0 {
        return Ok(());
    }
    let err = io::Error::last_os_error();
    if err.raw_os_error() == Some(libc::ESRCH) {
        return Ok(());
    }
    Err(err)
}

/// How long a group gets to exit on SIGTERM before SIGKILL.
///
/// Short on purpose. The deadline has already passed, so this is the courtesy
/// window for a package manager to unwind, not a second timeout.
const GROUP_TERM_GRACE: Duration = Duration::from_secs(5);

/// Whether this action's real work is an `rpm-ostree` transaction. Such work
/// runs inside `rpm-ostreed`'s own cgroup (rpm-ostree is a thin D-Bus client),
/// not this process group, so a group signal cannot reach it — it must be
/// cancelled with `rpm-ostree cancel` instead (#142). `program` is usually
/// `sudo`, so the real command is found in the arguments.
fn is_rpm_ostree_action(program: &str, args: &[String]) -> bool {
    let is_ostree = |s: &str| s == "rpm-ostree" || s.ends_with("/rpm-ostree");
    is_ostree(program) || args.iter().any(|a| is_ostree(a))
}

/// The argv for a privileged, non-interactive signal to a whole process group:
/// `sudo -n /usr/lib/sysknife/action-steps signal <SIGNAL> -<pgid>`. Run as
/// root, it reaches the root children a `sudo` action forked that the
/// unprivileged daemon cannot signal itself. `-n` never prompts (the sysknife
/// sudoers entry is NOPASSWD). The helper reads `-<pgid>` as a group and
/// refuses -1, 0 and 1 for every caller, which a `kill -s *` grant could not.
fn root_group_kill_argv(signal: &str, pgid: i32) -> Vec<String> {
    vec![
        "-n".to_string(),
        "/usr/lib/sysknife/action-steps".to_string(),
        "signal".to_string(),
        signal.to_string(),
        format!("-{pgid}"),
    ]
}

/// Counts `run_sudo` invocations so a test can prove the escalation path did
/// (not) fire without needing a real sudo. Test-only.
#[cfg(test)]
static SUDO_INVOCATIONS: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);

/// Run a bounded, output-discarding `sudo` command for the privileged reaper.
/// Best-effort for the *verdict* (the caller re-probes the group to decide the
/// outcome), but the exit status is logged so a later "could not be confirmed
/// stopped" line can be told apart from a misconfigured sudoers grant or a
/// missing `sudo` — the reaper failing and the process genuinely wedging look
/// identical from the group probe alone.
async fn run_sudo(args: Vec<String>) {
    #[cfg(test)]
    SUDO_INVOCATIONS.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
    let fut = tokio::process::Command::new("sudo")
        .args(&args)
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status();
    let joined = args.join(" ");
    match tokio::time::timeout(REAP_WAIT_CAP, fut).await {
        Ok(Ok(status)) if status.success() => {}
        Ok(Ok(status)) => {
            eprintln!("[sysknife-daemon] privileged reap `sudo {joined}` exited {status}")
        }
        Ok(Err(e)) => {
            eprintln!("[sysknife-daemon] privileged reap `sudo {joined}` could not run: {e}")
        }
        Err(_) => eprintln!(
            "[sysknife-daemon] privileged reap `sudo {joined}` timed out after {}s",
            REAP_WAIT_CAP.as_secs()
        ),
    }
}

/// The first privileged reap command (the args passed to `sudo`) for an action
/// whose group survived the daemon's own signals: `rpm-ostree cancel` for an
/// rpm-ostree transaction (its work is in another cgroup), otherwise a root TERM
/// to the action's own process group. Split out so the dispatch and the exact
/// argv are unit-testable without running `sudo`.
fn reap_command(pgid: i32, program: &str, args: &[String]) -> Vec<String> {
    if is_rpm_ostree_action(program, args) {
        vec![
            "-n".to_string(),
            "/usr/bin/rpm-ostree".to_string(),
            "cancel".to_string(),
        ]
    } else {
        root_group_kill_argv("TERM", pgid)
    }
}

/// Last-resort privileged reap for a group the daemon's own signals could not
/// stop (its members run as root). Cancels an `rpm-ostree` transaction, or root
/// TERM→KILLs the process group. This is the *termination* half of #140's
/// detect-and-veto, so `ActionNotStopped` becomes a genuine last resort rather
/// than the expected path for every sudo action.
async fn privileged_reap(pgid: i32, program: &str, args: &[String]) {
    run_sudo(reap_command(pgid, program, args)).await;
    // rpm-ostree cancel is a single, blocking call; only the group-kill path
    // escalates TERM → KILL. The client process blocks until the daemon-side
    // transaction resolves (completes, errors, or cancels), so once `cancel`
    // returns the transaction is stopped and the client group exits — which is
    // why the caller's group probe (of the client) correctly reflects the
    // transaction, even though the work itself ran in rpm-ostreed's cgroup.
    if is_rpm_ostree_action(program, args) {
        return;
    }
    tokio::time::sleep(Duration::from_millis(300)).await;
    if !probe_group(pgid).is_gone() {
        run_sudo(root_group_kill_argv("KILL", pgid)).await;
    }
}

/// Upper bound on any single `child.wait()` in the timeout path.
///
/// The direct child of a `sudo` action runs as root and this daemon cannot
/// signal it, so `wait()` on that child can block until the privileged work
/// finishes on its own — hours. The action timeout exists to stop a hang, so it
/// must not itself become one. Every wait here is bounded by this; an unreaped
/// child becomes the subreaper's problem, not a wedged connection.
const REAP_WAIT_CAP: Duration = Duration::from_secs(2);

/// Stop an action that outran the deadline, and report honestly whether it
/// actually stopped.
///
/// Signals the child's whole **process group**, not just its pid. The daemon
/// runs unprivileged and elevates through `sudo`, which forks: signalling the
/// pid alone leaves the privileged work running (issue #140). SIGTERM first so a
/// package manager can unwind, then SIGKILL.
///
/// An unprivileged daemon cannot signal a process running as root, which every
/// `sudo` action's real work does. When the group survives the daemon's own
/// signals it therefore escalates to a privileged reaper ([`privileged_reap`]):
/// a root kill of the group via the sudoers-authorised `action-steps signal`, or an
/// `rpm-ostree cancel` for a transaction that lives in another cgroup (#142).
/// Only when even that cannot confirm the group gone does it return
/// [`ExecutorError::ActionNotStopped`] — now a genuine last resort — and the
/// dispatcher refuses the automatic rollback rather than starting a second
/// privileged transaction over the first.
async fn kill_and_reap(
    child: &mut tokio::process::Child,
    program: &str,
    args: &[String],
    cause: StopCause,
) -> ExecutorError {
    let secs = action_timeout().as_secs();
    let why = cause.describe(secs);
    let Some(pgid) = child.id().map(|pid| pid as i32) else {
        // Already reaped: the child exited between the deadline and here, so the
        // work is done and there is nothing to signal.
        eprintln!("[sysknife-daemon] {program} {why}; already exited");
        return cause.into_error(program, secs);
    };

    // A pid-targeted floor. `start_kill` (SIGKILL to the direct child) always
    // lands when the child is ours to signal, which covers every non-`sudo`
    // action; the group signal below covers the grandchildren `sudo` forks.
    let _ = child.start_kill();
    if let Err(err) = signal_group(pgid, libc::SIGTERM) {
        eprintln!("[sysknife-daemon] SIGTERM to process group {pgid} failed: {err}");
    }

    // Reap the direct child first, bounded: an unreaped child is a zombie that
    // keeps the group alive and would make the probe below lie. Bounded because
    // a root `sudo` child can outlast any signal this daemon can send.
    let _ = tokio::time::timeout(REAP_WAIT_CAP, child.wait()).await;

    let grace = tokio::time::Instant::now() + GROUP_TERM_GRACE;
    while tokio::time::Instant::now() < grace && !probe_group(pgid).is_gone() {
        tokio::time::sleep(Duration::from_millis(50)).await;
    }
    if !probe_group(pgid).is_gone() {
        if let Err(err) = signal_group(pgid, libc::SIGKILL) {
            eprintln!("[sysknife-daemon] SIGKILL to process group {pgid} failed: {err}");
        }
        tokio::time::sleep(Duration::from_millis(200)).await;
        let _ = tokio::time::timeout(REAP_WAIT_CAP, child.wait()).await;
    }

    // The group survived the daemon's own signals: its members run as root (a
    // `sudo` action's privileged child), which an unprivileged daemon cannot
    // signal. Escalate to a privileged reaper — a root kill of the group, or an
    // `rpm-ostree cancel` for a transaction that lives in another cgroup (#142).
    //
    // Escalate only for `AliveUnreachable` (EPERM): the members run as root, the
    // sudo action's privileged child the daemon cannot signal. A same-uid process
    // wedged in D-state (`AliveReachable`) or an `Unknown` errno would not be
    // helped by a root signal, so those fall straight through to
    // `ActionNotStopped` rather than a pointless sudo round-trip.
    //
    // Signalling the group by its numeric pgid is safe against pid reuse: POSIX
    // keeps a process-group id allocated for the group's whole lifetime (while it
    // has any member), so a probe reporting the group alive guarantees the pgid
    // still names THIS action's group, never a recycled unrelated process.
    if probe_group(pgid) == GroupState::AliveUnreachable {
        eprintln!(
            "[sysknife-daemon] {program} process group {pgid} survived as root; \
             escalating to a privileged reap"
        );
        privileged_reap(pgid, program, args).await;
        tokio::time::sleep(Duration::from_millis(200)).await;
        let _ = tokio::time::timeout(REAP_WAIT_CAP, child.wait()).await;
    }

    match probe_group(pgid) {
        GroupState::Gone => {
            eprintln!("[sysknife-daemon] {program} {why}; process group {pgid} stopped");
            cause.into_error(program, secs)
        }
        state => {
            eprintln!(
                "[sysknife-daemon] {program} {why} and process group {pgid} \
                 could not be confirmed stopped ({state:?})"
            );
            ExecutorError::ActionNotStopped {
                program: program.to_string(),
                pgid,
                timeout_secs: secs,
            }
        }
    }
}

/// Why the executor is tearing down a still-running privileged child.
///
/// Both causes must stop the process group — a root child left running after the
/// executor has reported failure defeats the rollback interlock and the
/// one-privileged-action-at-a-time guarantee — but they are not the same event,
/// and reporting a read failure as a timeout would send an operator hunting a
/// deadline that never fired.
enum StopCause {
    /// The action's own deadline elapsed.
    Timeout,
    /// The daemon lost the ability to read the child (a non-UTF-8 line, a broken
    /// pipe, a `wait` that failed). Carries the error to surface once the group
    /// is confirmed stopped.
    Unreadable(io::Error),
}

impl StopCause {
    /// The operator-log fragment, e.g. `exceeded the 900s action timeout`.
    fn describe(&self, secs: u64) -> String {
        match self {
            StopCause::Timeout => format!("exceeded the {secs}s action timeout"),
            StopCause::Unreadable(err) => format!("could not be read ({err})"),
        }
    }

    /// The error to return once the group is confirmed gone. A group that
    /// survives reports [`ExecutorError::ActionNotStopped`] instead, whatever the
    /// cause — the caller needs to know work is still running far more than it
    /// needs to know why the executor gave up on it.
    fn into_error(self, program: &str, secs: u64) -> ExecutorError {
        match self {
            StopCause::Timeout => ExecutorError::Io(io::Error::new(
                io::ErrorKind::TimedOut,
                format!("{program} exceeded the {secs}s action timeout and was stopped"),
            )),
            StopCause::Unreadable(err) => ExecutorError::Io(err),
        }
    }
}

async fn execute_command_with_progress(
    program: &'static str,
    args: &[String],
    progress: UnboundedSender<String>,
) -> Result<ExecutionOutput, ExecutorError> {
    let mut child = tokio::process::Command::new(program)
        .args(args)
        // Own process group, so the deadline can signal the whole tree rather
        // than one pid. Without it the kill lands on `sudo`, which has already
        // forked the privileged work, and the action outlives the timeout that
        // claims to have stopped it. See issue #140.
        .process_group(0)
        // Null stdin, matching `execute_spec`. A background process group with a
        // controlling terminal would otherwise get SIGTTIN on a stdin read and
        // stop, burning the whole grace window before SIGKILL. No privileged
        // action should read the daemon's stdin regardless.
        .stdin(Stdio::null())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .spawn()
        .map_err(ExecutorError::Io)?;

    let stdout = child.stdout.take().expect("stdout was piped");
    let stderr = child.stderr.take().expect("stderr was piped");
    let stderr_task = tokio::spawn(async move {
        let mut buf = Vec::new();
        BufReader::new(stderr)
            .read_to_end(&mut buf)
            .await
            .map(|_| buf)
    });

    let deadline = tokio::time::Instant::now() + action_timeout();

    let mut lines = BufReader::new(stdout).lines();
    let mut stdout_buf = String::new();
    loop {
        // The deadline covers the whole action, not each read: a process that
        // emits one progress line an hour must still be cut off.
        let next = match tokio::time::timeout_at(deadline, lines.next_line()).await {
            Ok(Ok(line)) => line,
            // Losing the read is not a reason to walk away from a running root
            // child. `lines()` fails with `InvalidData` on non-UTF-8 output, so
            // this is reachable from any action whose stdout carries a byte
            // sequence outside UTF-8 — one oddly-encoded filename is enough.
            Ok(Err(err)) => {
                return Err(
                    kill_and_reap(&mut child, program, args, StopCause::Unreadable(err)).await,
                )
            }
            Err(_) => {
                return Err(kill_and_reap(&mut child, program, args, StopCause::Timeout).await)
            }
        };
        let Some(line) = next else { break };
        if !line.is_empty() {
            let _ = progress.send(line.clone());
        }
        stdout_buf.push_str(&line);
        stdout_buf.push('\n');
    }

    let exit_status = match tokio::time::timeout_at(deadline, child.wait()).await {
        Ok(Ok(status)) => status,
        // A failed `wait` leaves the child's fate unknown, which is the one state
        // the dispatcher must never treat as "stopped".
        Ok(Err(err)) => {
            return Err(kill_and_reap(&mut child, program, args, StopCause::Unreadable(err)).await)
        }
        Err(_) => return Err(kill_and_reap(&mut child, program, args, StopCause::Timeout).await),
    };
    let stderr_bytes = stderr_task
        .await
        .map_err(|_| ExecutorError::Io(io::Error::other("stderr reader task panicked")))?
        .map_err(ExecutorError::Io)?;

    Ok(ExecutionOutput {
        stdout: stdout_buf,
        stderr: String::from_utf8_lossy(&stderr_bytes).into_owned(),
        exit_code: exit_status.code().unwrap_or(-1),
    })
}

/// Parameter names accepted by each action, including deliberate aliases.
/// Keep this next to the builder so optional/defaulted parameters cannot mask
/// misspelled keys. Dispatcher-only actions use the same boundary check.
fn allowed_action_params(action_name: &str) -> Option<&'static [&'static str]> {
    Some(match action_name {
        "GetSystemState"
        | "CollectDiagnostics"
        | "GetDeploymentHistory"
        | "ListDeployments"
        | "UpdateSystem"
        | "CleanupDeployments"
        | "RebootSystem"
        | "RollbackDeployment"
        | "GetKernelArguments"
        | "GetLayeredPackages"
        | "ResetLayeredPackageOverride"
        | "GetPendingUpdates"
        | "ListPackageRepositories"
        | "ListServices"
        | "ListTimers"
        | "ReloadDaemon"
        | "GetDateTime"
        | "GetDiskUsage"
        | "ListProcesses"
        | "GetLvmReport"
        | "GetMounts"
        | "GetSudoGrants"
        | "RemoveRemoteSyslog"
        | "GetMemoryInfo"
        | "GetHostState"
        | "GetFirewallState"
        | "GetNetworkStatus"
        | "GetListeningPorts"
        | "GetNftablesRuleset"
        | "GetFirewallBackendState"
        | "ListUsers"
        | "ListGroups"
        | "AptUpdate"
        | "AptUpgrade"
        | "AptAutoremove"
        | "AptListInstalled"
        | "AptListUpgradable"
        | "AptHistoryList"
        | "SnapList"
        | "GrubGetKargs"
        | "CheckPendingReboot"
        | "UfwEnable"
        | "UfwDisable"
        | "UfwReset"
        | "DistroboxList"
        | "NetplanGetConfig"
        | "NetplanApply"
        | "NetplanGenerate"
        | "ProStatus"
        | "ProDetach"
        | "LivepatchStatus"
        | "MultipassList"
        | "UbuntuReleaseUpgrade"
        | "ResolvectlStatus"
        | "AppArmorStatus"
        | "CloudInitStatus"
        | "GetAuditRules"
        | "GetCertificates"
        | "RenewCertificates" => &[],
        "PinDeployment" | "UnpinDeployment" => &["index"],
        "RebaseSystem" => &["target_ref"],
        "SetKernelArguments" => &["add", "remove"],
        "ListFlatpakRemotes"
        | "ListInstalledFlatpaks"
        | "ListContainers"
        | "ListToolboxes"
        | "DeleteUser"
        | "LockUserAccount"
        | "UnlockUserAccount"
        | "GetAuthorizedKeys"
        | "UbuntuListFlatpaks" => &["user", "username"],
        "InstallFlatpak" | "UbuntuInstallFlatpak" => &["app_id", "remote", "user", "username"],
        "RemoveFlatpak"
        | "GetFlatpakAppInfo"
        | "UpdateFlatpak"
        | "UbuntuRemoveFlatpak"
        | "UbuntuUpdateFlatpak" => &["app_id", "user", "username"],
        "SearchFlatpakApps" | "AptSearch" => &["term"],
        "AddFlatpakRemote" => &["remote", "url", "user", "username"],
        "RemoveFlatpakRemote" => &["remote", "user", "username"],
        "CreateContainer" => &["image", "name", "user", "username"],
        "StartContainer" | "StopContainer" | "RemoveContainer" | "GetContainerInfo"
        | "RemoveToolbox" => &["name", "user", "username"],
        "InstallPackages" | "RemovePackages" => &["packages"],
        "AddLayeredPackage"
        | "RemoveLayeredPackage"
        | "RemoveBasePackage"
        | "GetAptPins"
        | "AptInstall"
        | "AptRemove"
        | "AptPurge"
        | "AptHold"
        | "AptUnhold"
        | "AptShow" => &["package"],
        "ReplaceLayeredPackage" => &["new", "old"],
        "AddPackageRepository" => &["repo_id", "repo_url"],
        "RemovePackageRepository" | "EnablePackageRepository" | "DisablePackageRepository" => {
            &["repo_id"]
        }
        "StartService"
        | "StopService"
        | "RestartService"
        | "MaskService"
        | "UnmaskService"
        | "GetServiceLogs"
        | "GetServiceStatus"
        | "ReloadService"
        | "GetServiceResourceLimits" => &["unit"],
        "SetServiceEnabled" => &["enabled", "unit"],
        "CreateScheduledJob" => &["command", "name", "schedule"],
        "SetServiceResourceLimits" => &[
            "cpu_quota",
            "memory_high",
            "memory_max",
            "tasks_max",
            "unit",
        ],
        "CreateToolbox" => &["image", "name", "release", "user", "username"],
        "SetHostname" => &["hostname"],
        "SetTimezone" => &["timezone"],
        "SetLocale" => &["locale"],
        "SetNtp" | "ConfigureUnattendedUpgrades" => &["enabled"],
        "SignalProcess" => &["pid", "signal"],
        "GetJournalLog" => &[
            "boot", "grep", "kernel", "lines", "priority", "since", "unit", "until",
        ],
        "VacuumJournal" => &["retain_days", "size_mb"],
        "ExtendLogicalVolume" => &["lv", "size", "vg"],
        "CreateLogicalVolume" => &["name", "size", "vg"],
        "CreateLvSnapshot" => &["origin", "size", "snapshot", "vg"],
        "GetSysctl" | "RemoveAuditRule" => &["key"],
        "SetSysctl" | "NetplanSet" => &["key", "value"],
        "AddMount" => &["device", "fstype", "mountpoint", "options"],
        "RemoveMount" => &["mountpoint"],
        "AddSwap" => &["file", "size_mb"],
        "RemoveSwap" => &["file"],
        "GrantSudoAccess" => &["commands", "name", "nopasswd", "runas", "user"],
        "RevokeSudoAccess" | "RemoveAptPin" | "RemoveLogRotation" | "AddPpa" | "RemovePpa"
        | "SnapRemove" | "SnapRefresh" | "SnapHold" | "SnapUnhold" | "SnapInfo" | "SnapRevert"
        | "SnapClassicInstall" | "DistroboxRemove" => &["name"],
        "SetAptPin" => &["name", "package", "pin", "priority"],
        "GetLogrotateStatus" => &["config"],
        "ConfigureLogRotation" => &["compress", "frequency", "name", "path", "rotate"],
        "ConfigureRemoteSyslog" => &["host", "port", "protocol"],
        "GetPasswordAging" => &["user"],
        "SetPasswordAging" => &["max_days", "min_days", "user", "warn_days"],
        "SetPasswordPolicy" => &["dcredit", "lcredit", "minlen", "ocredit", "ucredit"],
        "SetAccountLockout" => &["deny", "fail_interval", "unlock_time"],
        "ConfigureWifi" => &["password", "ssid"],
        "SetDnsServers" | "ResolvectlSetDns" => &["interface", "servers"],
        "ConfigureFirewall" => &["enabled", "service", "zone"],
        "CreateUser" => &["home", "shell", "user", "username"],
        "AddUserToGroup" | "RemoveUserFromGroup" => &["group", "user", "username"],
        "CreateGroup" => &["group", "system"],
        "DeleteGroup" => &["group"],
        "AddAuthorizedKey" | "RemoveAuthorizedKey" => &["public_key", "user", "username"],
        "SetSshdOption" => &["option", "value"],
        "SnapInstall" => &["auto_update", "channel", "name"],
        "GrubSetKargs" => &["append", "delete"],
        "UfwAllow" | "UfwDeny" => &["port_or_service"],
        "UfwStatus" => &["numbered"],
        "DistroboxCreate" => &["image", "name"],
        "UfwDeleteRule" => &["rule_number"],
        "UfwLimit" => &["target"],
        "ProAttach" => &["token"],
        "EnableProService" | "DisableProService" => &["service"],
        "AppArmorEnforce" | "AppArmorComplain" => &["profile_path"],
        "Fail2banStatus" => &["jail"],
        "Fail2banBanIp" | "Fail2banUnbanIp" => &["ip", "jail"],
        "ConfigureFail2banJail" => &["bantime", "enabled", "findtime", "maxretry", "name"],
        "AddAuditRule" => &["key", "path", "perms"],
        "ObtainCertificate" => &["challenge", "domain", "domains", "email"],
        "ListJobHistory" => &[
            "limit",
            "status_filter",
            "action_filter",
            "since_hours",
            "since",
        ],
        _ => return None,
    })
}

pub(crate) fn validate_action_params(
    action_name: &str,
    params: &Value,
) -> Result<(), ExecutorError> {
    let allowed = allowed_action_params(action_name)
        .ok_or_else(|| ExecutorError::UnknownAction(action_name.to_string()))?;
    let object = params
        .as_object()
        .ok_or(ExecutorError::InvalidParam("params"))?;
    if object.keys().any(|key| !allowed.contains(&key.as_str())) {
        return Err(ExecutorError::InvalidParam("unknown parameter"));
    }
    Ok(())
}

/// Map an action name and JSON params to an [`ActionSpec`].
///
/// Returns [`ExecutorError::UnknownAction`] for unrecognised names and
/// [`ExecutorError::MissingParam`] when a required param is absent, or
/// [`ExecutorError::InvalidParam`] for non-object params or unrecognised keys.
pub fn build_action_spec(action_name: &str, params: &Value) -> Result<ActionSpec, ExecutorError> {
    validate_action_params(action_name, params)?;
    match action_name {
        // ── Deployment: no params ─────────────────────────────────────────
        "GetSystemState" => Ok(deployment::get_system_state()),
        "CollectDiagnostics" => Ok(deployment::collect_diagnostics()),
        "GetDeploymentHistory" => Ok(deployment::get_deployment_history()),
        "ListDeployments" => Ok(deployment::list_deployments()),
        "UpdateSystem" => Ok(deployment::update_system()),
        "CleanupDeployments" => Ok(deployment::cleanup_deployments()),
        "RebootSystem" => Ok(deployment::reboot_system()),
        "RollbackDeployment" => Ok(deployment::rollback_deployment()),
        "GetKernelArguments" => Ok(deployment::get_kernel_arguments()),

        // ── Deployment: parameterized ─────────────────────────────────────
        "PinDeployment" => Ok(deployment::pin_deployment(require_u32(params, "index")?)),
        "UnpinDeployment" => Ok(deployment::unpin_deployment(require_u32(params, "index")?)),
        "RebaseSystem" => {
            let target_ref = require_str(params, "target_ref")?;
            let target_ref = validated_rebase_ref(target_ref, "target_ref")?;
            Ok(deployment::rebase_system(&target_ref))
        }
        "SetKernelArguments" => {
            let add = str_array_or_empty(params, "add")?;
            let remove = str_array_or_empty(params, "remove")?;
            // Reject dangerous kernel arguments that could bypass security
            // mechanisms or give unauthenticated root access on next boot.
            for arg in add.iter() {
                validated_safe_kernel_arg(arg, "add")?;
            }
            // Removal is screened too: stripping a protective arg reaches the
            // same end state as adding its weakening counterpart.
            for arg in remove.iter() {
                validated_safe_kernel_arg_removal(arg, "remove")?;
            }
            let add_refs: Vec<&str> = add.iter().map(String::as_str).collect();
            let remove_refs: Vec<&str> = remove.iter().map(String::as_str).collect();
            Ok(deployment::set_kernel_arguments(&add_refs, &remove_refs))
        }

        // ── Flatpak ───────────────────────────────────────────────────────
        // All user-scoped Flatpak operations require a `username` param so the
        // daemon can switch to that user's environment via `runuser -l`. This
        // ensures operations target the user's Flatpak installation
        // (~/.local/share/flatpak/) rather than the system store.
        "ListFlatpakRemotes" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            Ok(flatpak::list_flatpak_remotes(&username))
        }
        "InstallFlatpak" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let app_id = validated_safe_arg(require_str(params, "app_id")?, "app_id")?;
            // `remote` defaults to "flathub" — the universal Flatpak remote.
            // Models frequently omit it; accepting the default avoids a
            // MissingParam failure for the most common install case.
            let remote = params
                .get("remote")
                .and_then(|v| v.as_str())
                .unwrap_or("flathub");
            let remote = validated_safe_arg(remote, "remote")?;
            Ok(flatpak::install_flatpak(&username, &app_id, &remote))
        }
        "RemoveFlatpak" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let app_id = validated_safe_arg(require_str(params, "app_id")?, "app_id")?;
            Ok(flatpak::remove_flatpak(&username, &app_id))
        }
        "SearchFlatpakApps" => {
            let term = validated_safe_arg(require_str(params, "term")?, "term")?;
            Ok(flatpak::search_flatpak_apps(&term))
        }
        "AddFlatpakRemote" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let remote = validated_safe_arg(require_str(params, "remote")?, "remote")?;
            let url = validated_safe_arg(require_str(params, "url")?, "url")?;
            Ok(flatpak::add_flatpak_remote(&username, &remote, &url))
        }
        "RemoveFlatpakRemote" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let remote = validated_safe_arg(require_str(params, "remote")?, "remote")?;
            Ok(flatpak::remove_flatpak_remote(&username, &remote))
        }
        "GetFlatpakAppInfo" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let app_id = validated_safe_arg(require_str(params, "app_id")?, "app_id")?;
            Ok(flatpak::get_flatpak_app_info(&username, &app_id))
        }
        "ListInstalledFlatpaks" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            Ok(flatpak::list_installed_flatpaks(&username))
        }
        "UpdateFlatpak" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            // app_id is optional — omitting it updates all installed Flatpaks.
            // Empty string is treated as absent (no app specified → update all).
            let app_id = params
                .get("app_id")
                .and_then(|v| v.as_str())
                .filter(|id| !id.is_empty())
                .map(|id| validated_safe_arg(id, "app_id"))
                .transpose()?;
            Ok(flatpak::update_flatpak(&username, app_id.as_deref()))
        }

        // ── Containers ────────────────────────────────────────────────────
        // All container operations require a `username` param so the daemon can
        // switch to that user's rootless Podman environment via `runuser -l`.
        // Podman storage is per-user; running as the `sysknife` system user
        // would see an empty, unrelated container store.
        "ListContainers" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            Ok(containers::list_containers(&username))
        }
        "CreateContainer" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            let image = validated_safe_arg(require_str(params, "image")?, "image")?;
            Ok(containers::create_container(&username, &name, &image))
        }
        "StartContainer" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(containers::start_container(&username, &name))
        }
        "StopContainer" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(containers::stop_container(&username, &name))
        }
        "RemoveContainer" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(containers::remove_container(&username, &name))
        }
        "GetContainerInfo" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(containers::get_container_info(&username, &name))
        }

        // ── Layering ──────────────────────────────────────────────────────
        "GetLayeredPackages" => Ok(layering::get_layered_packages()),
        "ResetLayeredPackageOverride" => Ok(layering::reset_layered_package_override()),
        "InstallPackages" => {
            let pkgs = str_array_or_empty(params, "packages")?;
            let validated: Vec<String> = pkgs
                .iter()
                .map(|p| validated_install_package(p, "packages"))
                .collect::<Result<_, _>>()?;
            let refs: Vec<&str> = validated.iter().map(String::as_str).collect();
            Ok(layering::install_packages(&refs))
        }
        "RemovePackages" => {
            let pkgs = str_array_or_empty(params, "packages")?;
            let validated: Vec<String> = pkgs
                .iter()
                .map(|p| validated_install_package(p, "packages"))
                .collect::<Result<_, _>>()?;
            let refs: Vec<&str> = validated.iter().map(String::as_str).collect();
            Ok(layering::remove_packages(&refs))
        }
        "AddLayeredPackage" => {
            let package = validated_install_package(require_str(params, "package")?, "package")?;
            Ok(layering::add_layered_package(&package))
        }
        "RemoveLayeredPackage" => {
            let package = validated_install_package(require_str(params, "package")?, "package")?;
            Ok(layering::remove_layered_package(&package))
        }
        "ReplaceLayeredPackage" => {
            let old = validated_install_package(require_str(params, "old")?, "old")?;
            let new = validated_install_package(require_str(params, "new")?, "new")?;
            Ok(layering::replace_layered_package(&old, &new))
        }
        "RemoveBasePackage" => {
            let package = validated_install_package(require_str(params, "package")?, "package")?;
            Ok(layering::remove_base_package(&package))
        }
        "GetPendingUpdates" => Ok(layering::get_pending_updates()),

        // ── Package repositories ──────────────────────────────────────────
        "ListPackageRepositories" => Ok(package_repos::list_package_repositories()),
        "AddPackageRepository" => Ok(package_repos::add_package_repository(
            validated_repo_id(params)?,
            validated_no_newline(params, "repo_url")?,
        )),
        "RemovePackageRepository" => Ok(package_repos::remove_package_repository(
            validated_repo_id(params)?,
        )),
        "EnablePackageRepository" => Ok(package_repos::enable_package_repository(
            validated_repo_id(params)?,
        )),
        "DisablePackageRepository" => Ok(package_repos::disable_package_repository(
            validated_repo_id(params)?,
        )),

        // ── Services ─────────────────────────────────────────────────────
        "ListServices" => Ok(services::list_services()),
        "StartService" => {
            let unit = validated_activatable_unit(require_str(params, "unit")?, "unit")?;
            Ok(services::start_service(&unit))
        }
        "StopService" => {
            let unit = validated_stoppable_unit(require_str(params, "unit")?, "unit")?;
            Ok(services::stop_service(&unit))
        }
        "RestartService" => {
            // A restart is a stop and a start, so it clears both screens.
            let unit = validated_activatable_unit(require_str(params, "unit")?, "unit")?;
            let unit = validated_stoppable_unit(&unit, "unit")?;
            Ok(services::restart_service(&unit))
        }
        "SetServiceEnabled" => {
            let enabled = require_bool(params, "enabled")?;
            // Enabling brings the unit up at boot, so it must clear the root-shell
            // denylist; disabling one is a mitigation and stays allowed.
            let unit = if enabled {
                validated_activatable_unit(require_str(params, "unit")?, "unit")?
            } else {
                validated_unit_name(require_str(params, "unit")?, "unit")?
            };
            Ok(services::set_service_enabled(&unit, enabled))
        }
        "MaskService" => {
            let unit = validated_unit_name(require_str(params, "unit")?, "unit")?;
            Ok(services::mask_service(&unit))
        }
        "UnmaskService" => {
            let unit = validated_activatable_unit(require_str(params, "unit")?, "unit")?;
            Ok(services::unmask_service(&unit))
        }
        "GetServiceLogs" => {
            let unit = validated_unit_name(require_str(params, "unit")?, "unit")?;
            Ok(services::get_service_logs(&unit))
        }
        "GetServiceStatus" => {
            let unit = validated_unit_name(require_str(params, "unit")?, "unit")?;
            Ok(services::get_service_status(&unit))
        }
        "ReloadService" => {
            let unit = validated_unit_name(require_str(params, "unit")?, "unit")?;
            Ok(services::reload_service(&unit))
        }
        "ListTimers" => Ok(services::list_timers()),
        "ReloadDaemon" => Ok(services::reload_daemon()),
        "CreateScheduledJob" => {
            // Job name: safe logical name. The service module owns the
            // exact sysknife-<name> unit-path rendering used by preview.
            let name = require_str(params, "name")?;
            if services::scheduled_job_unit_paths(name).is_none() {
                return Err(ExecutorError::InvalidParam("name"));
            }
            // Command: reject control characters (newlines would inject extra
            // unit directives). systemd argv-splits ExecStart with no shell.
            let command = require_str(params, "command")?;
            if command.is_empty()
                || command.len() > MAX_SCHEDULED_COMMAND_LEN
                || command.chars().any(|c| c.is_control())
            {
                return Err(ExecutorError::InvalidParam("command"));
            }
            // Schedule: OnCalendar charset; the helper validates it semantically
            // with `systemd-analyze calendar`.
            let schedule = require_str(params, "schedule")?;
            if schedule.is_empty()
                || schedule.len() > MAX_SCHEDULE_EXPR_LEN
                || !schedule.chars().all(|c| {
                    c.is_ascii_alphanumeric()
                        || matches!(c, ' ' | ':' | ',' | '*' | '/' | '.' | '~' | '+' | '-')
                })
            {
                return Err(ExecutorError::InvalidParam("schedule"));
            }
            Ok(services::create_scheduled_job(name, command, schedule))
        }
        "GetServiceResourceLimits" => {
            let unit = validated_unit_name(require_str(params, "unit")?, "unit")?;
            Ok(services::get_service_resource_limits(&unit))
        }
        "SetServiceResourceLimits" => {
            // Not `validated_unit_name`: setting a property is neither an
            // activation nor a read, and this action is Medium-risk, so a
            // Dev-tier caller reaches it. See RESOURCE_LIMIT_PROTECTED_UNITS.
            let unit = validated_resource_limit_unit(require_str(params, "unit")?, "unit")?;
            // Build validated PROPERTY=VALUE assignments from whichever limits
            // were supplied; at least one is required.
            let mut assignments = Vec::new();
            if let Some(v) = optional_validated(params, "memory_max", validated_memory_limit)? {
                assignments.push(format!("MemoryMax={v}"));
            }
            if let Some(v) = optional_validated(params, "memory_high", validated_memory_limit)? {
                assignments.push(format!("MemoryHigh={v}"));
            }
            if let Some(v) = optional_validated(params, "cpu_quota", validated_cpu_quota)? {
                assignments.push(format!("CPUQuota={v}"));
            }
            if let Some(v) = optional_validated(params, "tasks_max", validated_tasks_max)? {
                assignments.push(format!("TasksMax={v}"));
            }
            if assignments.is_empty() {
                return Err(ExecutorError::MissingParam("memory_max"));
            }
            Ok(services::set_service_resource_limits(&unit, &assignments))
        }

        // ── Toolbox ───────────────────────────────────────────────────────
        // Toolbox operations require a `username` param — toolbox containers are
        // per-user (rootless Podman) and must be managed in the user's context.
        "ListToolboxes" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            Ok(toolbox::list_toolboxes(&username))
        }
        "CreateToolbox" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            let image = params
                .get("image")
                .and_then(|v| v.as_str())
                .map(|img| validated_safe_arg(img, "image"))
                .transpose()?;
            let release = params
                .get("release")
                .and_then(|v| v.as_str())
                .map(|r| validated_safe_arg(r, "release"))
                .transpose()?;
            Ok(toolbox::create_toolbox(
                &username,
                &name,
                release.as_deref(),
                image.as_deref(),
            ))
        }
        "RemoveToolbox" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(toolbox::remove_toolbox(&username, &name))
        }

        // ── Identity ─────────────────────────────────────────────────────
        "GetDateTime" => Ok(identity::get_datetime()),
        "SetHostname" => {
            let hostname = validated_hostname(require_str(params, "hostname")?, "hostname")?;
            Ok(identity::set_hostname(&hostname))
        }
        "SetTimezone" => {
            let timezone = validated_timezone(require_str(params, "timezone")?, "timezone")?;
            Ok(identity::set_timezone(&timezone))
        }
        "SetLocale" => {
            let locale = validated_locale(require_str(params, "locale")?, "locale")?;
            Ok(identity::set_locale(&locale))
        }
        "SetNtp" => Ok(identity::set_ntp(require_bool(params, "enabled")?)),

        // ── Filesystem ────────────────────────────────────────────────────
        "GetDiskUsage" => Ok(filesystem::disk_usage_spec()),

        // ── Processes ────────────────────────────────────────────────────
        "ListProcesses" => Ok(processes::list_processes_spec()),
        "SignalProcess" => {
            // pid may arrive as a JSON number or a numeric string.
            let pid = params
                .get("pid")
                .and_then(|v| {
                    v.as_u64()
                        .or_else(|| v.as_str().and_then(|s| s.trim().parse::<u64>().ok()))
                })
                .ok_or(ExecutorError::MissingParam("pid"))?;
            // Reject pid 0 (whole process group) and 1 (init/systemd); anything
            // outside the u32 pid space is invalid.
            if pid < 2 || pid > u32::MAX as u64 {
                return Err(ExecutorError::InvalidParam("pid"));
            }
            let signal = validated_kill_signal(
                params
                    .get("signal")
                    .and_then(|v| v.as_str())
                    .unwrap_or("TERM"),
            )?;
            Ok(processes::signal_process(pid as u32, signal))
        }

        // ── Journald ──────────────────────────────────────────────────────
        "GetJournalLog" => {
            let unit = optional_validated(params, "unit", validated_unit_name)?;
            let priority = optional_validated(params, "priority", validated_journal_priority)?;
            let since = optional_validated(params, "since", validated_journal_time)?;
            let until = optional_validated(params, "until", validated_journal_time)?;
            let grep = optional_validated(params, "grep", validated_journal_grep)?;
            // `lines` defaults to 100 and is clamped so an enormous value cannot
            // make the daemon buffer an unbounded journal dump.
            let lines = params
                .get("lines")
                .and_then(|v| v.as_u64())
                .unwrap_or(100)
                .clamp(1, MAX_JOURNAL_LINES) as u32;
            let boot = params
                .get("boot")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            let kernel = params
                .get("kernel")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            Ok(journald::get_journal_log(&journald::JournalQuery {
                lines,
                unit: unit.as_deref(),
                priority: priority.as_deref(),
                boot,
                kernel,
                since: since.as_deref(),
                until: until.as_deref(),
                grep: grep.as_deref(),
            }))
        }
        "VacuumJournal" => {
            // Exactly one of size_mb / retain_days selects the vacuum mode.
            let size_mb = params.get("size_mb").and_then(|v| v.as_u64());
            let retain_days = params.get("retain_days").and_then(|v| v.as_u64());
            match (size_mb, retain_days) {
                (Some(mb), None) if (1..=u32::MAX as u64).contains(&mb) => {
                    Ok(journald::vacuum_journal_by_size(mb as u32))
                }
                (None, Some(days)) if (1..=u32::MAX as u64).contains(&days) => {
                    Ok(journald::vacuum_journal_by_time(days as u32))
                }
                (None, None) => Err(ExecutorError::MissingParam("size_mb")),
                // both supplied, or an out-of-range value
                _ => Err(ExecutorError::InvalidParam("size_mb")),
            }
        }

        // ── Storage / LVM ───────────────────────────────────────────────────
        "GetLvmReport" => Ok(lvm::get_lvm_report()),
        "ExtendLogicalVolume" => {
            let vg = validated_lvm_name(require_str(params, "vg")?, "vg")?;
            let lv = validated_lvm_name(require_str(params, "lv")?, "lv")?;
            let size = validated_lvm_size(require_str(params, "size")?, "size")?;
            Ok(lvm::extend_logical_volume(&vg, &lv, &size))
        }
        "CreateLogicalVolume" => {
            let vg = validated_lvm_name(require_str(params, "vg")?, "vg")?;
            let name = validated_lvm_name(require_str(params, "name")?, "name")?;
            let size = validated_lvm_size(require_str(params, "size")?, "size")?;
            Ok(lvm::create_logical_volume(&vg, &name, &size))
        }
        "CreateLvSnapshot" => {
            let vg = validated_lvm_name(require_str(params, "vg")?, "vg")?;
            let origin = validated_lvm_name(require_str(params, "origin")?, "origin")?;
            let snapshot = validated_lvm_name(require_str(params, "snapshot")?, "snapshot")?;
            let size = validated_lvm_size(require_str(params, "size")?, "size")?;
            Ok(lvm::create_lv_snapshot(&vg, &origin, &snapshot, &size))
        }

        // ── Kernel / sysctl ─────────────────────────────────────────────────
        "GetSysctl" => {
            // `key` is optional — absent means dump the whole table (sysctl -a).
            let key = optional_validated(params, "key", validated_sysctl_key)?;
            Ok(sysctl::get_sysctl(key.as_deref()))
        }
        "SetSysctl" => {
            let key = validated_sysctl_key(require_str(params, "key")?, "key")?;
            let value = validated_sysctl_value(require_str(params, "value")?, "value")?;
            Ok(sysctl::set_sysctl(&key, &value))
        }

        // ── Filesystem mounts / swap ────────────────────────────────────────
        "GetMounts" => Ok(mounts::get_mounts()),
        "AddMount" => {
            let device = validated_mount_device(require_str(params, "device")?, "device")?;
            let mountpoint =
                validated_mount_point(require_str(params, "mountpoint")?, "mountpoint")?;
            let fstype = validated_fstype(require_str(params, "fstype")?, "fstype")?;
            let options = optional_validated(params, "options", validated_mount_options)?;
            Ok(mounts::add_mount(
                &device,
                &mountpoint,
                &fstype,
                options.as_deref(),
            ))
        }
        "RemoveMount" => {
            let mountpoint =
                validated_mount_point(require_str(params, "mountpoint")?, "mountpoint")?;
            Ok(mounts::remove_mount(&mountpoint))
        }
        "AddSwap" => {
            let file = validated_swap_path(require_str(params, "file")?, "file")?;
            let size_mb = require_u32(params, "size_mb")?;
            // 1 MiB .. 1 TiB — reject 0 (empty) and absurdly large requests.
            if !(1..=MAX_SWAP_SIZE_MB).contains(&size_mb) {
                return Err(ExecutorError::InvalidParam("size_mb"));
            }
            Ok(mounts::add_swap(&file, size_mb))
        }
        "RemoveSwap" => {
            let file = validated_swap_path(require_str(params, "file")?, "file")?;
            Ok(mounts::remove_swap(&file))
        }

        // ── Scoped sudoers.d ────────────────────────────────────────────────
        "GetSudoGrants" => Ok(sudoers::get_sudo_grants()),
        "GrantSudoAccess" => {
            let name = validated_sudoers_name(require_str(params, "name")?, "name")?;
            let user = validated_username(require_str(params, "user")?, "user")?;
            let commands = validated_sudo_commands(require_str(params, "commands")?, "commands")?;
            // runas defaults to root; if given it must be "ALL" or a username.
            let runas = match params
                .get("runas")
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())
            {
                Some("ALL") => Some("ALL".to_string()),
                Some(u) => Some(validated_username(u, "runas")?),
                None => None,
            };
            let nopasswd = params
                .get("nopasswd")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            // `commands = "ALL"` together with `nopasswd` mints a standing,
            // passwordless, unrestricted root credential (`user ALL=(ALL)
            // NOPASSWD: ALL`). Unlike every other action here, the effect
            // outlives the job: it is a permanent privilege grant, not a
            // one-time change, and it is indistinguishable from the daemon's
            // own authority thereafter. Require the caller to give up one of
            // the two dimensions — scope the commands, or keep the password
            // prompt. `visudo` would happily accept the combination, so this
            // is the only place it can be refused.
            //
            // `"ALL"` was the only spelling this refused, and
            // `validated_sudo_commands` accepts `/bin/bash`, which is the same
            // capability written differently: `user ALL=(root) NOPASSWD:
            // /bin/bash` is a standing passwordless root shell and `visudo -cf`
            // takes it without complaint. A shell-equivalent list is held to
            // the same line as `"ALL"` now. See SHELL_EQUIVALENT_COMMANDS for
            // what that list covers and what it deliberately leaves to the
            // preview.
            let shell_equivalent = shell_equivalent_sudo_command(&commands);
            if (commands == "ALL" || shell_equivalent.is_some()) && nopasswd {
                return Err(ExecutorError::InvalidParam("commands"));
            }
            Ok(sudoers::grant_sudo_access(
                &name,
                &user,
                &commands,
                runas.as_deref(),
                nopasswd,
            ))
        }
        "RevokeSudoAccess" => {
            let name = validated_sudoers_name(require_str(params, "name")?, "name")?;
            Ok(sudoers::revoke_sudo_access(&name))
        }

        // ── apt pinning (preferences.d) ─────────────────────────────────────
        "GetAptPins" => {
            let package = optional_validated(params, "package", validated_apt_package)?;
            Ok(apt_preferences::get_apt_pins(package.as_deref()))
        }
        "SetAptPin" => {
            let name = validated_apt_pin_name(require_str(params, "name")?, "name")?;
            let package = validated_apt_package(require_str(params, "package")?, "package")?;
            let pin = validated_apt_pin_expr(require_str(params, "pin")?, "pin")?;
            let priority = params
                .get("priority")
                .and_then(|v| v.as_i64())
                .ok_or(ExecutorError::MissingParam("priority"))?;
            if !(-1..=1000).contains(&priority) {
                return Err(ExecutorError::InvalidParam("priority"));
            }
            Ok(apt_preferences::set_apt_pin(
                &name, &package, &pin, priority,
            ))
        }
        "RemoveAptPin" => {
            let name = validated_apt_pin_name(require_str(params, "name")?, "name")?;
            Ok(apt_preferences::remove_apt_pin(&name))
        }

        // ── Log management (logrotate + rsyslog) ────────────────────────────
        "GetLogrotateStatus" => {
            let config = optional_validated(params, "config", validated_log_path)?;
            Ok(logging::get_logrotate_status(config.as_deref()))
        }
        "ConfigureLogRotation" => {
            let name = validated_sudoers_name(require_str(params, "name")?, "name")?;
            let frequency = require_str(params, "frequency")?;
            if !matches!(frequency, "daily" | "weekly" | "monthly") {
                return Err(ExecutorError::InvalidParam("frequency"));
            }
            let rotate = require_u32(params, "rotate")?;
            if rotate > 1000 {
                return Err(ExecutorError::InvalidParam("rotate"));
            }
            let path = validated_log_rotation(require_str(params, "path")?, rotate)?;
            let compress = params
                .get("compress")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            Ok(logging::configure_log_rotation(
                &name, &path, frequency, rotate, compress,
            ))
        }
        "RemoveLogRotation" => {
            let name = validated_sudoers_name(require_str(params, "name")?, "name")?;
            Ok(logging::remove_log_rotation(&name))
        }
        "ConfigureRemoteSyslog" => {
            let host = validated_syslog_host(require_str(params, "host")?, "host")?;
            let port = require_u32(params, "port")?;
            if !(1..=crate::actions::validate::MAX_PORT).contains(&port) {
                return Err(ExecutorError::InvalidParam("port"));
            }
            let protocol = require_str(params, "protocol")?;
            if !matches!(protocol, "tcp" | "udp") {
                return Err(ExecutorError::InvalidParam("protocol"));
            }
            Ok(logging::configure_remote_syslog(
                &host,
                port as u16,
                protocol,
            ))
        }
        "RemoveRemoteSyslog" => Ok(logging::remove_remote_syslog()),

        // ── PAM password policy ───────────────────────────────────────────
        "GetPasswordAging" => {
            let user = validated_username(require_str(params, "user")?, "user")?;
            Ok(pam::get_password_aging(&user))
        }
        "SetPasswordAging" => {
            let user = validated_username(require_str(params, "user")?, "user")?;
            // chage days: 0..=99999 (chage's own ceiling). At least one required.
            let mut flags = Vec::new();
            for (key, opt) in [("max_days", "-M"), ("min_days", "-m"), ("warn_days", "-W")] {
                if let Some(n) = params.get(key).and_then(|v| v.as_u64()) {
                    if n > MAX_PASSWORD_AGE_DAYS {
                        return Err(ExecutorError::InvalidParam(key));
                    }
                    flags.push(opt.to_string());
                    flags.push(n.to_string());
                }
            }
            if flags.is_empty() {
                return Err(ExecutorError::MissingParam("max_days"));
            }
            Ok(pam::set_password_aging(&user, &flags))
        }
        "SetPasswordPolicy" => {
            // minlen 1..=128; *credit knobs -64..=64 (negative = require that
            // many chars of the class). At least one required.
            let mut extra = Vec::new();
            if let Some(n) = params.get("minlen").and_then(|v| v.as_u64()) {
                if !(1..=MAX_PASSWORD_MINLEN).contains(&n) {
                    return Err(ExecutorError::InvalidParam("minlen"));
                }
                extra.push("--minlen".to_string());
                extra.push(n.to_string());
            }
            for (key, flag) in [
                ("dcredit", "--dcredit"),
                ("ucredit", "--ucredit"),
                ("lcredit", "--lcredit"),
                ("ocredit", "--ocredit"),
            ] {
                if let Some(n) = params.get(key).and_then(|v| v.as_i64()) {
                    if !(-64..=64).contains(&n) {
                        return Err(ExecutorError::InvalidParam(key));
                    }
                    extra.push(flag.to_string());
                    extra.push(n.to_string());
                }
            }
            if extra.is_empty() {
                return Err(ExecutorError::MissingParam("minlen"));
            }
            Ok(pam::set_password_policy(&extra))
        }
        "SetAccountLockout" => {
            // deny 1..=1000; unlock_time/fail_interval seconds 0..=604800 (7d).
            let mut extra = Vec::new();
            if let Some(n) = params.get("deny").and_then(|v| v.as_u64()) {
                if !(1..=1000).contains(&n) {
                    return Err(ExecutorError::InvalidParam("deny"));
                }
                extra.push("--deny".to_string());
                extra.push(n.to_string());
            }
            for (key, flag) in [
                ("unlock_time", "--unlock-time"),
                ("fail_interval", "--fail-interval"),
            ] {
                if let Some(n) = params.get(key).and_then(|v| v.as_u64()) {
                    if n > MAX_LOCKOUT_WINDOW_SECS {
                        return Err(ExecutorError::InvalidParam(key));
                    }
                    extra.push(flag.to_string());
                    extra.push(n.to_string());
                }
            }
            if extra.is_empty() {
                return Err(ExecutorError::MissingParam("deny"));
            }
            Ok(pam::set_account_lockout(&extra))
        }

        // ── System info ──────────────────────────────────────────────────
        "GetMemoryInfo" => Ok(system_info::get_memory_info_spec()),
        "GetHostState" => Ok(system_info::get_host_state()),

        // ── Network ───────────────────────────────────────────────────────
        "GetFirewallState" => Ok(network::get_firewall_state()),
        "GetNetworkStatus" => Ok(network::get_network_status()),
        "GetListeningPorts" => Ok(network::get_listening_ports()),
        "GetNftablesRuleset" => Ok(network::get_nftables_ruleset()),
        "GetFirewallBackendState" => Ok(network::get_firewall_backend_state()),
        "ConfigureWifi" => {
            let ssid = validated_safe_arg(require_str(params, "ssid")?, "ssid")?;
            // password is optional — open networks connect without one.
            let password = params
                .get("password")
                .and_then(|v| v.as_str())
                .filter(|p| !p.is_empty())
                .map(|p| validated_safe_arg(p, "password"))
                .transpose()?;
            Ok(network::configure_wifi(&ssid, password.as_deref()))
        }
        "SetDnsServers" => {
            let interface = validated_safe_arg(require_str(params, "interface")?, "interface")?;
            let servers = str_array_or_empty(params, "servers")?;
            let validated: Vec<String> = servers
                .iter()
                .map(|s| validated_safe_arg(s, "servers"))
                .collect::<Result<_, _>>()?;
            let refs: Vec<&str> = validated.iter().map(String::as_str).collect();
            Ok(network::set_dns_servers(&interface, &refs))
        }
        "ConfigureFirewall" => {
            let zone = validated_safe_arg(require_str(params, "zone")?, "zone")?;
            let service = validated_safe_arg(require_str(params, "service")?, "service")?;
            Ok(network::configure_firewall(
                &zone,
                &service,
                require_bool(params, "enabled")?,
            ))
        }

        // ── Users ─────────────────────────────────────────────────────────
        "ListUsers" => Ok(users::list_users()),
        "ListGroups" => Ok(users::list_groups()),
        "CreateUser" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let shell = params
                .get("shell")
                .and_then(|v| v.as_str())
                .map(|s| validated_safe_arg(s, "shell"))
                .transpose()?;
            let home = params
                .get("home")
                .and_then(|v| v.as_str())
                .map(|h| validated_home_dir(h, "home"))
                .transpose()?;
            Ok(users::create_user(
                &username,
                shell.as_deref(),
                home.as_deref(),
            ))
        }
        "DeleteUser" => {
            let username = validated_username_not_critical(resolve_username(params)?, "username")?;
            Ok(users::delete_user(&username))
        }
        "AddUserToGroup" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let group = validated_group(require_str(params, "group")?, "group")?;
            Ok(users::add_user_to_group(&username, &group))
        }
        "RemoveUserFromGroup" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let group = validated_group(require_str(params, "group")?, "group")?;
            Ok(users::remove_user_from_group(&username, &group))
        }
        "CreateGroup" => {
            let group = validated_group(require_str(params, "group")?, "group")?;
            let system = params
                .get("system")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            Ok(users::create_group(&group, system))
        }
        "DeleteGroup" => {
            let group = validated_group_not_critical(require_str(params, "group")?, "group")?;
            Ok(users::delete_group(&group))
        }
        "LockUserAccount" => {
            let username = validated_username_not_critical(resolve_username(params)?, "username")?;
            Ok(users::lock_user_account(&username))
        }
        "UnlockUserAccount" => {
            let username = validated_username_not_critical(resolve_username(params)?, "username")?;
            Ok(users::unlock_user_account(&username))
        }

        // ── SSH ──────────────────────────────────────────────────────────
        "GetAuthorizedKeys" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            Ok(ssh::get_authorized_keys(&username))
        }
        "AddAuthorizedKey" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let public_key = validated_public_key(require_str(params, "public_key")?)?;
            Ok(ssh::add_authorized_key(&username, &public_key))
        }
        "RemoveAuthorizedKey" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let public_key = validated_public_key(require_str(params, "public_key")?)?;
            Ok(ssh::remove_authorized_key(&username, &public_key))
        }
        "SetSshdOption" => {
            // Allowlist the option name and its permitted values (the helper
            // re-validates as defense-in-depth). This is deliberately not an
            // arbitrary sshd_config editor.
            let option = require_str(params, "option")?;
            let value = require_str(params, "value")?;
            let allowed_values: &[&str] = match option {
                "PermitRootLogin" => &["yes", "no", "prohibit-password", "forced-commands-only"],
                "PasswordAuthentication"
                | "PubkeyAuthentication"
                | "X11Forwarding"
                | "PermitEmptyPasswords" => &["yes", "no"],
                _ => return Err(ExecutorError::InvalidParam("option")),
            };
            if !allowed_values.contains(&value) {
                return Err(ExecutorError::InvalidParam("value"));
            }
            Ok(ssh::set_sshd_option(option, value))
        }

        // ── apt ──────────────────────────────────────────────────────────
        "AptUpdate" => Ok(apt::apt_update()),
        "AptUpgrade" => Ok(apt::apt_upgrade()),
        "AptInstall" => {
            let package = validated_install_package(require_str(params, "package")?, "package")?;
            Ok(apt::apt_install(&package))
        }
        "AptRemove" => {
            let package = validated_unmodified_package(require_str(params, "package")?, "package")?;
            Ok(apt::apt_remove(&package))
        }
        "AptPurge" => {
            let package = validated_unmodified_package(require_str(params, "package")?, "package")?;
            Ok(apt::apt_purge(&package))
        }
        "AptAutoremove" => Ok(apt::apt_autoremove()),
        "AptHold" => {
            let package = validated_unmodified_package(require_str(params, "package")?, "package")?;
            Ok(apt::apt_hold(&package))
        }
        "AptUnhold" => {
            let package = validated_unmodified_package(require_str(params, "package")?, "package")?;
            Ok(apt::apt_unhold(&package))
        }
        "AptSearch" => {
            let term = validated_safe_arg(require_str(params, "term")?, "term")?;
            Ok(apt::apt_search(&term))
        }
        "AptListInstalled" => Ok(apt::apt_list_installed()),
        "AptShow" => {
            let package = validated_apt_show_package(require_str(params, "package")?, "package")?;
            Ok(apt::apt_show(&package))
        }
        "AptListUpgradable" => Ok(apt::apt_list_upgradable()),
        "AptHistoryList" => Ok(apt::apt_history_list()),
        "ConfigureUnattendedUpgrades" => Ok(apt::configure_unattended_upgrades(require_bool(
            params, "enabled",
        )?)),

        // ── ppa ──────────────────────────────────────────────────────────
        "AddPpa" => {
            let name = validated_ppa_name(require_str(params, "name")?, "name")?;
            Ok(ppa::add_ppa(&name))
        }
        "RemovePpa" => {
            let name = validated_ppa_name(require_str(params, "name")?, "name")?;
            Ok(ppa::remove_ppa(&name))
        }

        // ── snap ─────────────────────────────────────────────────────────
        "SnapInstall" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            let channel = params
                .get("channel")
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())
                .map(|s| validated_safe_arg(s, "channel"))
                .transpose()?;
            let auto_update = params
                .get("auto_update")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            snap::snap_install(&name, channel.as_deref(), auto_update).map_err(|e| match e {
                snap::SnapInstallError::InvalidArg { param, .. } => {
                    ExecutorError::InvalidParam(param)
                }
            })
        }
        "SnapRemove" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(snap::snap_remove(&name))
        }
        "SnapRefresh" => {
            let name = params
                .get("name")
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())
                .map(|s| validated_safe_arg(s, "name"))
                .transpose()?;
            Ok(snap::snap_refresh(name.as_deref()))
        }
        "SnapHold" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(snap::snap_hold(&name))
        }
        "SnapUnhold" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(snap::snap_unhold(&name))
        }
        "SnapList" => Ok(snap::snap_list()),
        "SnapInfo" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(snap::snap_info(&name))
        }
        "SnapRevert" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(snap::snap_revert(&name))
        }
        "SnapClassicInstall" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(snap::snap_classic_install(&name))
        }

        // ── grub ─────────────────────────────────────────────────────────
        "GrubGetKargs" => Ok(grub::grub_get_kargs()),
        "GrubSetKargs" => {
            let append: Vec<String> = params
                .get("append")
                .and_then(|v| v.as_array())
                .map(|arr| {
                    arr.iter()
                        .filter_map(|v| v.as_str())
                        .map(String::from)
                        .collect()
                })
                .unwrap_or_default();
            let delete: Vec<String> = params
                .get("delete")
                .and_then(|v| v.as_array())
                .map(|arr| {
                    arr.iter()
                        .filter_map(|v| v.as_str())
                        .map(String::from)
                        .collect()
                })
                .unwrap_or_default();
            // Validate each arg in both lists. `append` gets the charset check
            // (rejects `=`, `,`, shell metacharacters — the latter also blocks
            // CSV injection into the helper's comma-separated list) *and* the
            // kernel-arg denylist, so a bare `single`/`s`/`1` cannot boot the
            // host into a single-user root shell — parity with
            // SetKernelArguments. `delete` gets the charset check plus the
            // removal screen: dropping `module.sig_enforce=1` or `lockdown=`
            // weakens the next boot exactly as adding its counterpart would.
            for a in &append {
                validated_safe_arg(a, "append")?;
                validated_safe_kernel_arg(a, "append")?;
            }
            for d in &delete {
                validated_safe_arg(d, "delete")?;
                validated_safe_kernel_arg_removal(d, "delete")?;
            }
            // The constructor itself enforces "at least one of append/delete
            // non-empty" — this is the single source of truth for the invariant.
            let append_refs: Vec<&str> = append.iter().map(String::as_str).collect();
            let delete_refs: Vec<&str> = delete.iter().map(String::as_str).collect();
            grub::grub_set_kargs(&append_refs, &delete_refs)
                .map_err(|_| ExecutorError::MissingParam("append or delete"))
        }

        // ── reboot ────────────────────────────────────────────────────────
        "CheckPendingReboot" => Ok(reboot::check_pending_reboot()),

        // ── ufw ──────────────────────────────────────────────────────────
        "UfwEnable" => Ok(ufw::ufw_enable()),
        "UfwDisable" => Ok(ufw::ufw_disable()),
        "UfwAllow" => {
            let port_or_service = validated_port_or_service(
                require_str(params, "port_or_service")?,
                "port_or_service",
            )?;
            Ok(ufw::ufw_allow(&port_or_service))
        }
        "UfwDeny" => {
            let port_or_service = validated_port_or_service(
                require_str(params, "port_or_service")?,
                "port_or_service",
            )?;
            Ok(ufw::ufw_deny(&port_or_service))
        }
        "UfwReset" => Ok(ufw::ufw_reset()),
        "UfwStatus" => {
            let numbered = match params.get("numbered") {
                None => false,
                Some(value) => value
                    .as_bool()
                    .ok_or(ExecutorError::InvalidParam("numbered"))?,
            };
            Ok(ufw::ufw_status_with_numbered(numbered))
        }

        // ── distrobox ────────────────────────────────────────────────────
        "DistroboxList" => Ok(distrobox::distrobox_list()),
        "DistroboxCreate" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            let image = validated_safe_arg(require_str(params, "image")?, "image")?;
            Ok(distrobox::distrobox_create(&name, &image))
        }
        "DistroboxRemove" => {
            let name = validated_safe_arg(require_str(params, "name")?, "name")?;
            Ok(distrobox::distrobox_remove(&name))
        }

        // ── netplan ──────────────────────────────────────────────────────
        "NetplanGetConfig" => Ok(netplan::netplan_get_config()),
        "NetplanApply" => Ok(netplan::netplan_apply()),
        "NetplanSet" => {
            let key = validated_safe_arg(require_str(params, "key")?, "key")?;
            let value = validated_safe_arg(require_str(params, "value")?, "value")?;
            Ok(netplan::netplan_set(&key, &value))
        }
        "NetplanGenerate" => Ok(netplan::netplan_generate()),

        // ── ufw Tier 3 ────────────────────────────────────────────────────
        "UfwDeleteRule" => {
            let rule_number = require_positive_u32(params, "rule_number")?;
            ufw::ufw_delete_rule(rule_number)
                .map_err(|_| ExecutorError::InvalidParam("rule_number"))
        }
        "UfwLimit" => {
            let target = validated_port_or_service(require_str(params, "target")?, "target")?;
            Ok(ufw::ufw_limit(&target))
        }

        // ── Ubuntu Pro ────────────────────────────────────────────────────
        "ProStatus" => Ok(ubuntu_pro::pro_status()),
        "ProAttach" => {
            // token is a credential: read it from params but do NOT log it.
            let token = require_str(params, "token")?;
            // Minimal structural validation: non-empty, no shell metacharacters.
            let token = validated_safe_arg(token, "token")?;
            Ok(ubuntu_pro::pro_attach(&token))
        }
        "ProDetach" => Ok(ubuntu_pro::pro_detach()),
        "EnableProService" => {
            let service = validated_pro_service(require_str(params, "service")?, "service")?;
            Ok(ubuntu_pro::enable_pro_service(&service))
        }
        "DisableProService" => {
            let service = validated_pro_service(require_str(params, "service")?, "service")?;
            Ok(ubuntu_pro::disable_pro_service(&service))
        }

        // ── Livepatch ─────────────────────────────────────────────────────
        "LivepatchStatus" => Ok(livepatch::livepatch_status()),

        // ── Multipass ─────────────────────────────────────────────────────
        "MultipassList" => Ok(multipass::multipass_list()),

        // ── Release upgrade ───────────────────────────────────────────────
        "UbuntuReleaseUpgrade" => Ok(release_upgrade::ubuntu_release_upgrade()),

        // ── resolvectl (cross-distro / systemd-resolved) ──────────────────
        "ResolvectlStatus" => Ok(resolvectl::resolvectl_status()),
        "ResolvectlSetDns" => {
            let interface = validated_safe_arg(require_str(params, "interface")?, "interface")?;
            let raw_servers: Vec<String> = params
                .get("servers")
                .and_then(|v| v.as_array())
                .map(|arr| {
                    arr.iter()
                        .filter_map(|v| v.as_str())
                        .map(String::from)
                        .collect()
                })
                .unwrap_or_default();
            if raw_servers.is_empty() {
                return Err(ExecutorError::MissingParam("servers"));
            }
            // Parse every server string as a typed IpAddr before passing to the
            // constructor. This rejects leading-dash strings (flag injection) and
            // malformed addresses that would silently misconfigure systemd-resolved.
            let mut parsed_servers: Vec<IpAddr> = Vec::with_capacity(raw_servers.len());
            for s in &raw_servers {
                let addr = IpAddr::from_str(s).map_err(|_| ExecutorError::InvalidIpAddress {
                    param: "servers",
                    value: s.clone(),
                })?;
                parsed_servers.push(addr);
            }
            Ok(resolvectl::resolvectl_set_dns(&interface, &parsed_servers))
        }

        // ── apparmor ──────────────────────────────────────────────────────
        "AppArmorStatus" => Ok(apparmor::apparmor_status()),
        "AppArmorEnforce" => {
            let profile_path =
                validated_apparmor_profile(require_str(params, "profile_path")?, "profile_path")?;
            Ok(apparmor::apparmor_enforce(&profile_path))
        }
        "AppArmorComplain" => {
            let profile_path =
                validated_apparmor_profile(require_str(params, "profile_path")?, "profile_path")?;
            Ok(apparmor::apparmor_complain(&profile_path))
        }

        // ── cloud-init ────────────────────────────────────────────────────
        "CloudInitStatus" => Ok(cloudinit::cloud_init_status()),

        // ── Ubuntu Flatpak ─────────────────────────────────────────────────
        "UbuntuInstallFlatpak" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let app_id = validated_safe_arg(require_str(params, "app_id")?, "app_id")?;
            let remote = validated_safe_arg(require_str(params, "remote")?, "remote")?;
            Ok(flatpak::ubuntu_install_flatpak(&username, &app_id, &remote))
        }
        "UbuntuRemoveFlatpak" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let app_id = validated_safe_arg(require_str(params, "app_id")?, "app_id")?;
            Ok(flatpak::ubuntu_remove_flatpak(&username, &app_id))
        }
        "UbuntuUpdateFlatpak" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            let app_id = params
                .get("app_id")
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())
                .map(|s| validated_safe_arg(s, "app_id"))
                .transpose()?;
            Ok(flatpak::ubuntu_update_flatpak(&username, app_id.as_deref()))
        }
        "UbuntuListFlatpaks" => {
            let username = validated_username(resolve_username(params)?, "username")?;
            Ok(flatpak::ubuntu_list_flatpaks(&username))
        }

        // ── fail2ban ──────────────────────────────────────────────────────
        "Fail2banStatus" => {
            let jail = params
                .get("jail")
                .and_then(|v| v.as_str())
                .filter(|s| !s.is_empty())
                .map(|s| validated_safe_arg(s, "jail"))
                .transpose()?;
            fail2ban::fail2ban_status(jail.as_deref()).map_err(|e| match e {
                fail2ban::Fail2banError::InvalidIpAddress(_) => ExecutorError::InvalidParam("jail"),
                fail2ban::Fail2banError::InvalidJail(_) => ExecutorError::InvalidParam("jail"),
            })
        }
        "Fail2banBanIp" => {
            let jail = validated_safe_arg(require_str(params, "jail")?, "jail")?;
            let ip = require_str(params, "ip")?;
            fail2ban::fail2ban_ban_ip(&jail, ip).map_err(|e| match e {
                fail2ban::Fail2banError::InvalidIpAddress(v) => ExecutorError::InvalidIpAddress {
                    param: "ip",
                    value: v,
                },
                fail2ban::Fail2banError::InvalidJail(_) => ExecutorError::InvalidParam("jail"),
            })
        }
        "Fail2banUnbanIp" => {
            let jail = validated_safe_arg(require_str(params, "jail")?, "jail")?;
            let ip = require_str(params, "ip")?;
            fail2ban::fail2ban_unban_ip(&jail, ip).map_err(|e| match e {
                fail2ban::Fail2banError::InvalidIpAddress(v) => ExecutorError::InvalidIpAddress {
                    param: "ip",
                    value: v,
                },
                fail2ban::Fail2banError::InvalidJail(_) => ExecutorError::InvalidParam("jail"),
            })
        }
        "ConfigureFail2banJail" => {
            let name = validated_sudoers_name(require_str(params, "name")?, "name")?;
            let mut extra = Vec::new();
            if let Some(n) = params.get("enabled").and_then(|v| v.as_bool()) {
                extra.push("--enabled".to_string());
                extra.push(if n { "true" } else { "false" }.to_string());
            }
            if let Some(n) = params.get("maxretry").and_then(|v| v.as_u64()) {
                if !(1..=100).contains(&n) {
                    return Err(ExecutorError::InvalidParam("maxretry"));
                }
                extra.push("--maxretry".to_string());
                extra.push(n.to_string());
            }
            for (key, flag) in [("bantime", "--bantime"), ("findtime", "--findtime")] {
                if let Some(n) = params.get(key).and_then(|v| v.as_u64()) {
                    if n > MAX_FAIL2BAN_WINDOW_SECS {
                        return Err(ExecutorError::InvalidParam(key));
                    }
                    extra.push(flag.to_string());
                    extra.push(n.to_string());
                }
            }
            if extra.is_empty() {
                return Err(ExecutorError::MissingParam("maxretry"));
            }
            fail2ban::configure_fail2ban_jail(&name, &extra).map_err(|e| match e {
                fail2ban::Fail2banError::InvalidIpAddress(_) => ExecutorError::InvalidParam("name"),
                fail2ban::Fail2banError::InvalidJail(_) => ExecutorError::InvalidParam("name"),
            })
        }

        // ── auditd file-watch rules ───────────────────────────────────────
        "GetAuditRules" => Ok(auditd::get_audit_rules()),
        "AddAuditRule" => {
            let path = validated_audit_path(require_str(params, "path")?, "path")?;
            let perms = validated_audit_perms(require_str(params, "perms")?, "perms")?;
            let key = validated_sudoers_name(require_str(params, "key")?, "key")?;
            Ok(auditd::add_audit_rule(&path, &perms, &key))
        }
        "RemoveAuditRule" => {
            let key = validated_sudoers_name(require_str(params, "key")?, "key")?;
            Ok(auditd::remove_audit_rule(&key))
        }

        // ── certbot / ACME ────────────────────────────────────────────────
        "GetCertificates" => Ok(certbot::get_certificates()),
        "ObtainCertificate" => {
            // Accept a "domains" array or a single "domain" string; ≥1 required.
            let mut domains = Vec::new();
            if let Some(arr) = params.get("domains").and_then(|v| v.as_array()) {
                for d in arr {
                    let s = d.as_str().ok_or(ExecutorError::InvalidParam("domains"))?;
                    domains.push(validated_domain(s, "domains")?);
                }
            } else if let Some(d) = params.get("domain").and_then(|v| v.as_str()) {
                domains.push(validated_domain(d, "domain")?);
            }
            if domains.is_empty() {
                return Err(ExecutorError::MissingParam("domains"));
            }
            let email = validated_email(require_str(params, "email")?, "email")?;
            let challenge = params
                .get("challenge")
                .and_then(|v| v.as_str())
                .unwrap_or("standalone");
            if !matches!(challenge, "standalone" | "nginx" | "apache") {
                return Err(ExecutorError::InvalidParam("challenge"));
            }
            Ok(certbot::obtain_certificate(&domains, &email, challenge))
        }
        "RenewCertificates" => Ok(certbot::renew_certificates()),

        _ => Err(ExecutorError::UnknownAction(action_name.to_string())),
    }
}

/// Execute an [`ActionSpec`] and return the output.
///
/// For `Command` mechanisms, the process is spawned and its stdout/stderr
/// are captured. For file mechanisms, the operation is performed directly
/// on the filesystem and an empty stdout is returned.
pub async fn execute_spec(spec: &ActionSpec) -> Result<ExecutionOutput, ExecutorError> {
    match &spec.mechanism {
        ActionMechanism::Command { program, args } => {
            // Spawned rather than `.output()`ed so the child can be killed on
            // timeout; `.output()` gives no handle to kill, so a hung process
            // would hold the task forever.
            let mut child = tokio::process::Command::new(program)
                .args(args)
                .stdin(Stdio::null())
                // Own process group: the deadline below must be able to stop the
                // whole tree, not just the pid we spawned. See issue #140.
                .process_group(0)
                .stdout(Stdio::piped())
                .stderr(Stdio::piped())
                .spawn()?;

            // `wait_with_output` consumes the child, which would leave nothing
            // to kill when the deadline fires. Drain the pipes in their own
            // tasks instead — draining also stops a chatty process from
            // blocking on a full pipe buffer while we wait.
            let stdout_h = child.stdout.take().expect("stdout was piped");
            let stderr_h = child.stderr.take().expect("stderr was piped");
            let stdout_task = tokio::spawn(async move {
                let mut buf = Vec::new();
                BufReader::new(stdout_h)
                    .read_to_end(&mut buf)
                    .await
                    .map(|_| buf)
            });
            let stderr_task = tokio::spawn(async move {
                let mut buf = Vec::new();
                BufReader::new(stderr_h)
                    .read_to_end(&mut buf)
                    .await
                    .map(|_| buf)
            });

            let status = match tokio::time::timeout(action_timeout(), child.wait()).await {
                Ok(Ok(status)) => status,
                // Same rule as the streaming path: a `wait` that fails leaves a
                // privileged child in an unknown state, so stop the group before
                // reporting the failure upward.
                Ok(Err(err)) => {
                    return Err(kill_and_reap(
                        &mut child,
                        program,
                        args,
                        StopCause::Unreadable(err),
                    )
                    .await)
                }
                Err(_) => {
                    return Err(kill_and_reap(&mut child, program, args, StopCause::Timeout).await)
                }
            };
            let join =
                |e| ExecutorError::Io(io::Error::other(format!("reader task panicked: {e}")));
            let stdout = stdout_task.await.map_err(join)??;
            let stderr = stderr_task.await.map_err(join)??;

            Ok(ExecutionOutput {
                stdout: String::from_utf8_lossy(&stdout).into_owned(),
                stderr: String::from_utf8_lossy(&stderr).into_owned(),
                exit_code: status.code().unwrap_or(-1),
            })
        }
        ActionMechanism::FileScan { path } => {
            let mut entries = tokio::fs::read_dir(path).await?;
            let mut names = Vec::new();
            while let Some(entry) = entries.next_entry().await? {
                names.push(entry.file_name().to_string_lossy().into_owned());
            }
            names.sort();
            Ok(ExecutionOutput {
                stdout: names.join("\n"),
                stderr: String::new(),
                exit_code: 0,
            })
        }
        ActionMechanism::FileWrite { path, content } => {
            if let Some(parent) = std::path::Path::new(path).parent() {
                tokio::fs::create_dir_all(parent).await?;
            }
            tokio::fs::write(path, content).await?;
            Ok(ExecutionOutput {
                stdout: String::new(),
                stderr: String::new(),
                exit_code: 0,
            })
        }
        ActionMechanism::FilePatch {
            path,
            search,
            replace,
        } => {
            let content = tokio::fs::read_to_string(path).await?;
            let patched = content.replacen(search.as_str(), replace.as_str(), 1);
            if patched == content && !search.is_empty() {
                return Ok(ExecutionOutput {
                    stdout: String::new(),
                    stderr: format!("search string not found in file: {}", path),
                    exit_code: 1,
                });
            }
            tokio::fs::write(path, patched).await?;
            Ok(ExecutionOutput {
                stdout: String::new(),
                stderr: String::new(),
                exit_code: 0,
            })
        }
        ActionMechanism::FileDelete { path } => {
            tokio::fs::remove_file(path).await?;
            Ok(ExecutionOutput {
                stdout: String::new(),
                stderr: String::new(),
                exit_code: 0,
            })
        }
    }
}

fn require_str<'a>(params: &'a Value, key: &'static str) -> Result<&'a str, ExecutorError> {
    match params.get(key) {
        None => Err(ExecutorError::MissingParam(key)),
        Some(v) => v.as_str().ok_or(ExecutorError::InvalidParam(key)),
    }
}

/// Extract an optional string param and validate it. An absent key or an empty
/// string yields `None` (the filter is simply omitted); a present non-empty
/// value is passed through `validator`, propagating any validation error.
fn optional_validated<F>(
    params: &Value,
    key: &'static str,
    validator: F,
) -> Result<Option<String>, ExecutorError>
where
    F: FnOnce(&str, &'static str) -> Result<String, ExecutorError>,
{
    match params
        .get(key)
        .and_then(|v| v.as_str())
        .filter(|s| !s.is_empty())
    {
        Some(s) => Ok(Some(validator(s, key)?)),
        None => Ok(None),
    }
}

/// Extract the username from params, accepting either `"username"` or `"user"`
/// as the key.  The `"username"` key takes precedence.
///
/// Tolerates the `"user"` alias because LLMs trained on general Linux tooling
/// frequently produce `"user"` — accepting both here eliminates an entire class
/// of Describe/Execute failures without requiring the model to be perfect.
///
/// Returns [`ExecutorError::MissingParam`] if neither key is present,
/// [`ExecutorError::InvalidParam`] if the value is not a string.
fn resolve_username(params: &Value) -> Result<&str, ExecutorError> {
    params
        .get("username")
        .or_else(|| params.get("user"))
        .ok_or(ExecutorError::MissingParam("username"))
        .and_then(|v| v.as_str().ok_or(ExecutorError::InvalidParam("username")))
}

/// Validate a repo_id: must be non-empty and contain only ASCII letters,
/// digits, hyphens, and underscores. Rejects `/`, `.`, and whitespace to
/// prevent path traversal (e.g. `../cron.d/evil`) and shell injection.
fn validated_repo_id(params: &Value) -> Result<&str, ExecutorError> {
    let id = require_str(params, "repo_id")?;
    let valid = !id.is_empty()
        && id
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_');
    if valid {
        Ok(id)
    } else {
        Err(ExecutorError::InvalidParam("repo_id"))
    }
}

/// Validate that a string contains no newlines. Used for repo_url to prevent
/// INI-section injection into `.repo` file content.
fn validated_no_newline<'a>(
    params: &'a Value,
    key: &'static str,
) -> Result<&'a str, ExecutorError> {
    let val = require_str(params, key)?;
    if val.contains('\n') || val.contains('\r') {
        Err(ExecutorError::InvalidParam(key))
    } else {
        Ok(val)
    }
}

/// Validate an SSH public key: must start with a known key-type prefix,
/// contain only printable ASCII, no newlines, no single quotes (to prevent
/// shell injection in `sh -c` scripts), and be at most 8192 characters.
fn validated_public_key(s: &str) -> Result<String, ExecutorError> {
    const MAX_LEN: usize = 8192;
    const ALLOWED_PREFIXES: &[&str] = &[
        "ssh-rsa",
        "ssh-ed25519",
        "ssh-ed25519-sk",
        "ecdsa-sha2-nistp256",
        "ecdsa-sha2-nistp384",
        "ecdsa-sha2-nistp521",
        "sk-ssh-ed25519",
        "sk-ecdsa-sha2-nistp256",
    ];

    if s.is_empty() || s.len() > MAX_LEN {
        return Err(ExecutorError::InvalidParam("public_key"));
    }
    if !ALLOWED_PREFIXES.iter().any(|p| s.starts_with(p)) {
        return Err(ExecutorError::InvalidParam("public_key"));
    }
    // No newlines, no shell metacharacters, only printable ASCII.
    //
    // Blocked characters and why:
    //   '\''  — breaks single-quoted shell strings in add_authorized_key
    //   '|'   — shell pipe (the ssh key ops no longer build a sed address,
    //           but '|' never appears in a valid key, so keep rejecting it)
    //   ';'   — shell command separator
    //   '`'   — shell command substitution
    //   '$'   — shell variable expansion
    //   '\\'  — shell escape; could be used to smuggle other metacharacters
    //   '&'   — shell background / AND operator
    //
    // None of these characters appear in valid SSH public key data (type prefix,
    // base64 body, or ASCII comment) so this list is safe to block unconditionally.
    if s.chars().any(|c| {
        matches!(c, '\n' | '\r' | '\'' | '|' | ';' | '`' | '$' | '\\' | '&')
            || !c.is_ascii()
            || c.is_ascii_control()
    }) {
        return Err(ExecutorError::InvalidParam("public_key"));
    }
    Ok(s.to_string())
}

fn require_bool(params: &Value, key: &'static str) -> Result<bool, ExecutorError> {
    match params.get(key) {
        None => Err(ExecutorError::MissingParam(key)),
        Some(v) => v.as_bool().ok_or(ExecutorError::InvalidParam(key)),
    }
}

fn require_u32(params: &Value, key: &'static str) -> Result<u32, ExecutorError> {
    match params.get(key) {
        None => Err(ExecutorError::MissingParam(key)),
        Some(v) => {
            let n = v.as_u64().ok_or(ExecutorError::InvalidParam(key))?;
            u32::try_from(n).map_err(|_| ExecutorError::InvalidParam(key))
        }
    }
}

/// Like [`require_u32`] but additionally rejects zero.
///
/// Used for rule numbers and similar 1-based indices where 0 is never valid.
fn require_positive_u32(params: &Value, key: &'static str) -> Result<u32, ExecutorError> {
    let n = require_u32(params, key)?;
    if n == 0 {
        return Err(ExecutorError::InvalidParam(key));
    }
    Ok(n)
}

/// Returns a vec of owned strings from a JSON array, or an empty vec if the
/// key is absent or null. Returns [`ExecutorError::InvalidParam`] if the key
/// is present but not an array of strings.
fn str_array_or_empty(params: &Value, key: &'static str) -> Result<Vec<String>, ExecutorError> {
    match params.get(key) {
        None | Some(Value::Null) => Ok(vec![]),
        Some(Value::Array(arr)) => arr
            .iter()
            .map(|v| {
                v.as_str()
                    .map(String::from)
                    .ok_or(ExecutorError::InvalidParam(key))
            })
            .collect(),
        _ => Err(ExecutorError::InvalidParam(key)),
    }
}

/// The kernel arguments `SetKernelArguments` and `GrubSetKargs` may add, in the
/// normal form of [`normalized_kernel_arg`]. Anything not named is refused.
/// Documentation/admin-guide/kernel-parameters.txt and kernel-command-line(7)
/// describe each key.
///
/// An allowlist, because four review rounds of the denylists it replaced each
/// found another spelling past them: a hyphen in the key (`spectre-v2=off`), a
/// `kstrtobool` prefix (`mitigations=of`), a mitigation switch nobody had listed
/// (`nopku`, `spectre_v2_user=off`). One list, three copies: this file,
/// `packaging/sysknife-grub-kargs-edit` and `packaging/sysknife-action-steps`.
/// `tests/release/grub-kargs-edit.test.sh` and
/// `tests/release/action-steps.test.sh` compare them element by element.
///
/// Ordinary switches with no value; removable.
const KARG_FLAGS: &[&str] = &[
    "quiet",
    "splash",
    "rhgb",
    "nomodeset",
    "nowatchdog",
    "threadirqs",
];

/// Hardening switches with no value: they may be added and never removed.
const KARG_HARDENING_FLAGS: &[&str] = &["nosmt", "slab_nomerge"];

/// Ordinary keys that take any value of the one-token character set; removable.
const KARG_VALUE_KEYS: &[&str] = &[
    "console",
    "video",
    "loglevel",
    "hugepages",
    "hugepagesz",
    "default_hugepagesz",
    "nvme_core.default_ps_max_latency_us",
    "usbcore.autosuspend",
    "nvidia_drm.modeset",
    "nvidia_drm.fbdev",
    "i915.enable_psr",
    "amdgpu.dc",
    "acpi_backlight",
    "mem_sleep_default",
    "pcie_aspm",
    "transparent_hugepage",
    "zswap.enabled",
    "systemd.show_status",
    "plymouth.enable",
];

/// Ordinary keys whose value is a comma-separated list, each element from the
/// key's own set; removable. `rd.driver.blacklist=` keeps a driver from loading,
/// so it takes GPU drivers only: `tpm_crb` or `dm_crypt` there would switch off a
/// protection. `resume=` is not on the allowlist at all: at a device the caller
/// controls it boots a crafted hibernation image.
const KARG_LIST_VALUES: &[(&str, &[&str])] = &[(
    "rd.driver.blacklist",
    &[
        "nouveau",
        "nvidia",
        "nvidia_drm",
        "nvidia_modeset",
        "radeon",
        "amdgpu",
        "i915",
    ],
)];

/// Hardening keys with the only values that may be added. A hardening key is
/// never removed, with or without a value: libostree's
/// `ostree_kernel_args_delete` deletes a key's only value when asked for the bare
/// key, so `--delete=lockdown` would drop `lockdown=confidentiality`.
const KARG_HARDENING_VALUES: &[(&str, &[&str])] = &[
    ("lockdown", &["integrity", "confidentiality"]),
    ("module.sig_enforce", &["1"]),
    ("intel_iommu", &["on"]),
    ("amd_iommu", &["force_isolation"]),
    ("init_on_alloc", &["1"]),
    ("init_on_free", &["1"]),
    ("page_alloc.shuffle", &["1"]),
    ("randomize_kstack_offset", &["on"]),
    ("mitigations", &["auto", "auto,nosmt"]),
    ("pti", &["on"]),
    ("vsyscall", &["none"]),
    ("debugfs", &["off"]),
];

/// Exact downgrades, in normal form. Removing one hardens the host, so it is
/// allowed although its key is not an ordinary one; none of them can be added.
const KARG_WEAKENING: &[&str] = &[
    "selinux=0",
    "enforcing=0",
    "apparmor=0",
    "lockdown=none",
    "debugfs=on",
    "iommu=off",
    "intel_iommu=off",
    "nokaslr",
    "nopti",
    "nosmap",
    "nosmep",
    "nospectre_v1",
    "nospectre_v2",
    "nospec_store_bypass_disable",
    "nospectre_bhb",
    "single",
    "emergency",
    "rescue",
    "rd.break",
    "rd.shell",
    "systemd.debug_shell",
    "init=/bin/sh",
    "init=/bin/bash",
    "mitigations=off",
    "pti=off",
    "audit=0",
    "module.sig_enforce=0",
    "init_on_alloc=0",
    "init_on_free=0",
    "page_alloc.shuffle=0",
    "randomize_kstack_offset=off",
    "spectre_v2=off",
    "spec_store_bypass_disable=off",
    "mds=off",
    "tsx_async_abort=off",
    "mmio_stale_data=off",
    "retbleed=off",
    "srbds=off",
    "l1tf=off",
    "spectre_bhi=off",
    "gather_data_sampling=off",
    "reg_file_data_sampling=off",
];

/// The form both kernel-argument screens match on: lowercase, with `-` read as
/// `_` in the key. The kernel's `parameq()` (kernel/params.c) and systemd's
/// `proc_cmdline_key_streq()` treat the two as one character in a parameter
/// name, so `spectre-v2=off` is `spectre_v2=off`. The value keeps its spelling.
/// Every list entry above is written in this form.
fn normalized_kernel_arg(arg: &str) -> String {
    let lower = arg.to_lowercase();
    match lower.split_once('=') {
        Some((key, value)) => format!("{}={value}", key.replace('-', "_")),
        None => lower.replace('-', "_"),
    }
}

/// Screen a kernel argument that is about to be **added** to the boot line
/// (`SetKernelArguments`'s `add`, `GrubSetKargs`'s `append`): one boot-line
/// token, and on the allowlist. A flag is accepted bare, an ordinary key with
/// any non-empty value, a list key with every element in its set, a hardening
/// key with one of its listed values. `param`
/// names the request field in the error.
fn validated_safe_kernel_arg(arg: &str, param: &'static str) -> Result<(), ExecutorError> {
    validated_kernel_arg_token(arg, param)?;
    let normal = normalized_kernel_arg(arg);
    let allowed = match normal.split_once('=') {
        None => {
            KARG_FLAGS.contains(&normal.as_str()) || KARG_HARDENING_FLAGS.contains(&normal.as_str())
        }
        Some((key, value)) => {
            (!value.is_empty() && KARG_VALUE_KEYS.contains(&key))
                || KARG_LIST_VALUES
                    .iter()
                    .any(|(k, allowed)| *k == key && value.split(',').all(|v| allowed.contains(&v)))
                || KARG_HARDENING_VALUES
                    .iter()
                    .any(|(k, values)| *k == key && values.contains(&value))
        }
    };
    if allowed {
        Ok(())
    } else {
        Err(ExecutorError::InvalidParam(param))
    }
}

/// Require `arg` to be exactly one token of the kernel command line.
///
/// Both kargs screens judge one key and one value. The boot line is split on
/// whitespace, so a value carrying a second token behind a space, tab or newline
/// (or a quote that groups one) would land that token on the boot line
/// unscreened: `console=tty0 init=/bin/sh` is a listed key with a value. The
/// character set is `validated_safe_arg`'s plus `=` and `,`, which real
/// arguments need (`console=ttyS0,115200`), and the leading `-` stays refused.
fn validated_kernel_arg_token(arg: &str, param: &'static str) -> Result<(), ExecutorError> {
    if arg.is_empty() || arg.len() > crate::actions::validate::SAFE_ARG_MAX_BYTES {
        return Err(ExecutorError::InvalidParam(param));
    }
    if arg.starts_with('-') {
        return Err(ExecutorError::InvalidParam(param));
    }
    if !arg.chars().all(|c| {
        c.is_ascii_alphanumeric()
            || matches!(c, '.' | '_' | ':' | '/' | '+' | '@' | '-' | '=' | ',')
    }) {
        return Err(ExecutorError::InvalidParam(param));
    }
    Ok(())
}

/// Screen a kernel argument that is about to be **removed** from the boot line.
///
/// Removing a protective argument reaches the same next boot as adding its
/// weakening counterpart, so removal is allowed only for an ordinary key of the
/// allowlist (bare or with a value), or for an exact downgrade in
/// [`KARG_WEAKENING`], whose removal hardens the host. A hardening key and any
/// key nobody listed are refused, bare or with a value.
fn validated_safe_kernel_arg_removal(arg: &str, param: &'static str) -> Result<(), ExecutorError> {
    validated_kernel_arg_token(arg, param)?;
    let normal = normalized_kernel_arg(arg);
    let key = normal.split('=').next().unwrap_or(&normal);
    if KARG_WEAKENING.contains(&normal.as_str())
        || KARG_FLAGS.contains(&key)
        || KARG_VALUE_KEYS.contains(&key)
        || KARG_LIST_VALUES.iter().any(|(k, _)| *k == key)
    {
        Ok(())
    } else {
        Err(ExecutorError::InvalidParam(param))
    }
}

/// Validate a `kill` signal against a strict allowlist, returning the canonical
/// signal name for `kill -s <name>`.
///
/// Only stop/reload signals are permitted (`TERM`, `KILL`, `HUP`, `INT`); this
/// blocks exotic or numeric signals and, combined with the caller's `pid >= 2`
/// check, keeps `SignalProcess` from becoming an arbitrary-signal primitive.
/// Accepts case-insensitive input with an optional `SIG` prefix.
fn validated_kill_signal(s: &str) -> Result<&'static str, ExecutorError> {
    let normalized = s.trim().to_ascii_uppercase();
    match normalized.strip_prefix("SIG").unwrap_or(&normalized) {
        "TERM" => Ok("TERM"),
        "KILL" => Ok("KILL"),
        "HUP" => Ok("HUP"),
        "INT" => Ok("INT"),
        _ => Err(ExecutorError::InvalidParam("signal")),
    }
}

/// Return the rollback [`ActionSpec`] for `action_name`, or `None` if no
/// automatic rollback is defined.
///
/// Only the rpm-ostree deployment and layering actions support rollback —
/// they all revert via `rpm-ostree rollback`. All other actions either have
/// no sensible rollback or are low-risk enough that a rollback would be
/// net-harmful.
///
/// `RollbackDeployment` itself is excluded to prevent infinite recursion.
pub fn rollback_spec_for(action_name: &str) -> Option<ActionSpec> {
    match action_name {
        "UpdateSystem"
        | "InstallPackages"
        | "RemovePackages"
        | "RebaseSystem"
        | "SetKernelArguments"
        | "AddLayeredPackage"
        | "RemoveLayeredPackage"
        | "ReplaceLayeredPackage"
        | "ResetLayeredPackageOverride"
        | "RemoveBasePackage" => Some(ActionSpec {
            action_name: "RollbackDeployment",
            mechanism: ActionMechanism::Command {
                program: "rpm-ostree",
                args: vec!["rollback".to_string()],
            },
            risk_level: sysknife_types::RiskLevel::High,
            reboot_required: true,
            rollback_available: false,
        }),
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;
    use sysknife_types::RiskLevel;
    use tempfile::tempdir;

    // ── build_action_spec ─────────────────────────────────────────────────

    #[test]
    fn build_spec_rejects_unknown_keys_across_catalogue() {
        for name in sysknife_types::KNOWN_ACTION_NAMES {
            if crate::actions::DISPATCHER_INTERNAL_ACTIONS.contains(name) {
                continue;
            }
            assert!(
                matches!(
                    build_action_spec(name, &json!({"__unknown_param": 1})),
                    Err(ExecutorError::InvalidParam(_))
                ),
                "{name} must reject unknown keys before reading required params"
            );
        }
    }

    #[test]
    fn build_spec_rejects_non_object_params_across_catalogue() {
        for name in sysknife_types::KNOWN_ACTION_NAMES {
            if crate::actions::DISPATCHER_INTERNAL_ACTIONS.contains(name) {
                continue;
            }
            for params in [json!(null), json!([]), json!(42), json!(true), json!("{}")] {
                assert!(
                    matches!(
                        build_action_spec(name, &params),
                        Err(ExecutorError::InvalidParam(_))
                    ),
                    "{name} must reject non-object params: {params}"
                );
            }
        }
    }

    #[test]
    fn build_spec_rejects_cross_distro_kernel_argument_key() {
        assert!(matches!(
            build_action_spec("SetKernelArguments", &json!({"append": ["quiet"]})),
            Err(ExecutorError::InvalidParam(_))
        ));
        assert!(matches!(
            build_action_spec("UfwEnable", &json!({"x": 1})),
            Err(ExecutorError::InvalidParam(_))
        ));
    }

    #[test]
    fn build_spec_accepts_catalogue_params_and_username_aliases() {
        for name in sysknife_types::KNOWN_ACTION_NAMES {
            if crate::actions::DISPATCHER_INTERNAL_ACTIONS.contains(name) {
                continue;
            }
            // Complete valid examples exercise every parameter, including optional
            // keys; future required parameters make this catalogue test fail.
            let params = match *name {
                "PinDeployment" | "UnpinDeployment" => json!({"index": 0}),
                "RebaseSystem" => json!({"target_ref": "fedora-stable"}),
                "SetKernelArguments" => json!({"add": ["quiet"], "remove": ["splash"]}),
                "ListFlatpakRemotes"
                | "ListInstalledFlatpaks"
                | "ListContainers"
                | "ListToolboxes"
                | "DeleteUser"
                | "LockUserAccount"
                | "UnlockUserAccount"
                | "GetAuthorizedKeys"
                | "UbuntuListFlatpaks" => json!({"username": "alice"}),
                "InstallFlatpak" | "UbuntuInstallFlatpak" => {
                    json!({"username": "alice", "app_id": "org.mozilla.firefox", "remote": "flathub"})
                }
                "RemoveFlatpak"
                | "GetFlatpakAppInfo"
                | "UbuntuRemoveFlatpak"
                | "UpdateFlatpak"
                | "UbuntuUpdateFlatpak" => {
                    json!({"username": "alice", "app_id": "org.mozilla.firefox"})
                }
                "SearchFlatpakApps" | "AptSearch" => json!({"term": "vim"}),
                "AddFlatpakRemote" => {
                    json!({"username": "alice", "remote": "flathub", "url": "https://flathub.org/repo/flathub.flatpakrepo"})
                }
                "RemoveFlatpakRemote" => json!({"username": "alice", "remote": "flathub"}),
                "CreateContainer" => {
                    json!({"username": "alice", "name": "test", "image": "alpine"})
                }
                "StartContainer" | "StopContainer" | "RemoveContainer" | "GetContainerInfo"
                | "RemoveToolbox" => json!({"username": "alice", "name": "test"}),
                "InstallPackages" | "RemovePackages" => json!({"packages": ["vim"]}),
                "AddLayeredPackage"
                | "RemoveLayeredPackage"
                | "RemoveBasePackage"
                | "AptInstall"
                | "AptRemove"
                | "AptPurge"
                | "AptHold"
                | "AptUnhold"
                | "AptShow"
                | "GetAptPins" => json!({"package": "vim"}),
                "ReplaceLayeredPackage" => json!({"old": "vim", "new": "nano"}),
                "AddPackageRepository" => {
                    json!({"repo_id": "test", "repo_url": "https://example.com/repo"})
                }
                "RemovePackageRepository"
                | "EnablePackageRepository"
                | "DisablePackageRepository" => json!({"repo_id": "test"}),
                "StartService"
                | "StopService"
                | "RestartService"
                | "MaskService"
                | "UnmaskService"
                | "GetServiceLogs"
                | "GetServiceStatus"
                | "ReloadService"
                | "GetServiceResourceLimits" => json!({"unit": "nginx.service"}),
                "SetServiceEnabled" => json!({"unit": "nginx.service", "enabled": true}),
                "CreateScheduledJob" => {
                    json!({"name": "test", "command": "/usr/bin/true", "schedule": "daily"})
                }
                "SetServiceResourceLimits" => {
                    json!({"unit": "nginx.service", "memory_max": "1G", "memory_high": "512M", "cpu_quota": "50%", "tasks_max": "100"})
                }
                "CreateToolbox" => {
                    json!({"username": "alice", "name": "test", "image": "fedora-toolbox", "release": "41"})
                }
                "SetHostname" => json!({"hostname": "testhost"}),
                "SetTimezone" => json!({"timezone": "Europe/London"}),
                "SetLocale" => json!({"locale": "en_US.UTF-8"}),
                "SetNtp" | "ConfigureUnattendedUpgrades" => json!({"enabled": true}),
                "SignalProcess" => json!({"pid": 42, "signal": "TERM"}),
                "GetJournalLog" => {
                    json!({"unit": "nginx.service", "priority": "warning", "since": "yesterday", "until": "now", "grep": "error", "lines": 10, "boot": true, "kernel": false})
                }
                "VacuumJournal" => json!({"size_mb": 10}),
                "ExtendLogicalVolume" => json!({"vg": "vg0", "lv": "data", "size": "+1G"}),
                "CreateLogicalVolume" => json!({"vg": "vg0", "name": "data", "size": "1G"}),
                "CreateLvSnapshot" => {
                    json!({"vg": "vg0", "origin": "data", "snapshot": "backup", "size": "1G"})
                }
                "GetSysctl" => json!({"key": "net.ipv4.ip_forward"}),
                "SetSysctl" => json!({"key": "net.ipv4.ip_forward", "value": "1"}),
                "AddMount" => {
                    json!({"device": "/dev/sdb1", "mountpoint": "/mnt/data", "fstype": "ext4", "options": "defaults"})
                }
                "RemoveMount" => json!({"mountpoint": "/mnt/data"}),
                "AddSwap" => json!({"file": "/swapfile", "size_mb": 1024}),
                "RemoveSwap" => json!({"file": "/swapfile"}),
                "GrantSudoAccess" => {
                    json!({"name": "test", "user": "alice", "commands": "/usr/bin/uptime", "runas": "root", "nopasswd": true})
                }
                "RevokeSudoAccess" | "RemoveAptPin" | "RemoveLogRotation" => {
                    json!({"name": "test"})
                }
                "SetAptPin" => {
                    json!({"name": "test", "package": "vim", "pin": "version 1.*", "priority": 500})
                }
                "GetLogrotateStatus" => json!({"config": "/var/log/app.log"}),
                "ConfigureLogRotation" => {
                    json!({"name": "test", "path": "/var/log/app.log", "frequency": "daily", "rotate": 7, "compress": true})
                }
                "ConfigureRemoteSyslog" => {
                    json!({"host": "logs.example.com", "port": 514, "protocol": "tcp"})
                }
                "GetPasswordAging" => json!({"user": "alice"}),
                "SetPasswordAging" => {
                    json!({"user": "alice", "max_days": 90, "min_days": 1, "warn_days": 7})
                }
                "SetPasswordPolicy" => {
                    json!({"minlen": 12, "dcredit": -1, "ucredit": -1, "lcredit": -1, "ocredit": -1})
                }
                "SetAccountLockout" => json!({"deny": 5, "unlock_time": 600, "fail_interval": 900}),
                "ConfigureWifi" => json!({"ssid": "testwifi", "password": "examplepassword"}),
                "SetDnsServers" | "ResolvectlSetDns" => {
                    json!({"interface": "eth0", "servers": ["1.1.1.1"]})
                }
                "ConfigureFirewall" => json!({"zone": "public", "service": "ssh", "enabled": true}),
                "CreateUser" => {
                    json!({"username": "alice", "shell": "/bin/bash", "home": "/home/alice"})
                }
                "AddUserToGroup" | "RemoveUserFromGroup" => {
                    json!({"username": "alice", "group": "developers"})
                }
                "CreateGroup" => json!({"group": "developers", "system": true}),
                "DeleteGroup" => json!({"group": "developers"}),
                "AddAuthorizedKey" | "RemoveAuthorizedKey" => {
                    json!({"username": "alice", "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAITestKey alice"})
                }
                "SetSshdOption" => json!({"option": "PasswordAuthentication", "value": "no"}),
                "AddPpa" | "RemovePpa" => json!({"name": "deadsnakes/ppa"}),
                "SnapInstall" => json!({"name": "test", "channel": "stable", "auto_update": true}),
                "SnapRemove" | "SnapRefresh" | "SnapHold" | "SnapUnhold" | "SnapInfo"
                | "SnapRevert" | "SnapClassicInstall" | "DistroboxRemove" => {
                    json!({"name": "test"})
                }
                "GrubSetKargs" => json!({"append": ["quiet"], "delete": ["splash"]}),
                "UfwAllow" | "UfwDeny" => json!({"port_or_service": "22/tcp"}),
                "UfwStatus" => json!({"numbered": true}),
                "DistroboxCreate" => json!({"name": "test", "image": "ubuntu"}),
                "NetplanSet" => json!({"key": "ethernets.eth0.dhcp4", "value": "true"}),
                "UfwDeleteRule" => json!({"rule_number": 1}),
                "UfwLimit" => json!({"target": "ssh"}),
                "ProAttach" => json!({"token": "exampletoken"}),
                "EnableProService" | "DisableProService" => json!({"service": "esm-apps"}),
                "AppArmorEnforce" | "AppArmorComplain" => {
                    json!({"profile_path": "/etc/apparmor.d/usr.bin.test"})
                }
                "Fail2banStatus" => json!({"jail": "sshd"}),
                "Fail2banBanIp" | "Fail2banUnbanIp" => json!({"jail": "sshd", "ip": "192.0.2.1"}),
                "ConfigureFail2banJail" => {
                    json!({"name": "sshd", "enabled": true, "maxretry": 5, "bantime": 600, "findtime": 900})
                }
                "AddAuditRule" => json!({"path": "/etc/passwd", "perms": "wa", "key": "identity"}),
                "RemoveAuditRule" => json!({"key": "identity"}),
                "ObtainCertificate" => {
                    json!({"domains": ["example.com"], "domain": "example.com", "email": "admin@example.com", "challenge": "standalone"})
                }
                _ => json!({}),
            };
            build_action_spec(name, &params)
                .unwrap_or_else(|err| panic!("valid parameters rejected for {name}: {err}"));
            if params.get("username").is_some() {
                let mut aliased = params;
                let username = aliased.as_object_mut().unwrap().remove("username").unwrap();
                aliased["user"] = username;
                build_action_spec(name, &aliased)
                    .unwrap_or_else(|err| panic!("user alias rejected for {name}: {err}"));
            }
        }
        for params in [json!({"retain_days": 7}), json!({"size_mb": 10})] {
            build_action_spec("VacuumJournal", &params).unwrap();
        }
        build_action_spec(
            "ObtainCertificate",
            &json!({"domain": "example.com", "email": "admin@example.com"}),
        )
        .unwrap();
        build_action_spec("SignalProcess", &json!({"pid": "42"})).unwrap();
        build_action_spec("SetKernelArguments", &json!({"add": null, "remove": null})).unwrap();
    }

    #[test]
    fn build_spec_no_params_for_get_system_state() {
        let spec = build_action_spec("GetSystemState", &json!({})).unwrap();
        assert_eq!(spec.action_name, "GetSystemState");
        assert_eq!(spec.risk_level, RiskLevel::Low);
    }

    #[test]
    fn build_spec_get_datetime_is_low_risk() {
        let spec = build_action_spec("GetDateTime", &json!({})).unwrap();
        assert_eq!(spec.action_name, "GetDateTime");
        assert_eq!(spec.risk_level, RiskLevel::Low);
        assert!(!spec.reboot_required);
    }

    #[test]
    fn build_spec_unknown_action_returns_error() {
        let err = build_action_spec("NonExistent", &json!({})).unwrap_err();
        assert!(
            matches!(&err, ExecutorError::UnknownAction(n) if n == "NonExistent"),
            "expected UnknownAction, got: {err}"
        );
    }

    #[test]
    fn build_spec_missing_param_for_install_flatpak() {
        // username is the first required param; its absence is reported first.
        let err = build_action_spec("InstallFlatpak", &json!({})).unwrap_err();
        assert!(
            matches!(err, ExecutorError::MissingParam("username")),
            "expected MissingParam(username), got: {err}"
        );
    }

    /// LLMs trained on standard Linux tooling frequently produce `"user"` instead
    /// of `"username"`.  `resolve_username` accepts both keys so these actions
    /// never fail with a spurious MissingParam.
    #[test]
    fn build_spec_flatpak_accepts_user_alias() {
        let spec = build_action_spec("ListInstalledFlatpaks", &json!({ "user": "alice" })).unwrap();
        assert_eq!(spec.action_name, "ListInstalledFlatpaks");
    }

    /// `resolve_username` prefers `"username"` when both keys are present.
    #[test]
    fn build_spec_resolve_username_prefers_explicit_username() {
        let spec = build_action_spec(
            "ListInstalledFlatpaks",
            &json!({ "username": "alice", "user": "bob" }),
        )
        .unwrap();
        // Verify it didn't error — the "alice" value passes validation.
        assert_eq!(spec.action_name, "ListInstalledFlatpaks");
    }

    /// `remote` defaults to "flathub" when absent — eliminates the most common
    /// model omission without changing behaviour when the param is explicit.
    #[test]
    fn build_spec_install_flatpak_defaults_remote_to_flathub() {
        let spec = build_action_spec(
            "InstallFlatpak",
            &json!({ "username": "alice", "app_id": "org.mozilla.firefox" }),
        )
        .unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "flatpak".to_string(),
                    "alice".to_string(),
                    "install".to_string(),
                    "--user".to_string(),
                    "-y".to_string(),
                    "flathub".to_string(),
                    "org.mozilla.firefox".to_string(),
                ],
            }
        );
    }

    #[test]
    fn build_spec_install_flatpak_injects_app_and_remote() {
        let spec = build_action_spec(
            "InstallFlatpak",
            &json!({
                "username": "alice",
                "app_id": "org.mozilla.firefox",
                "remote": "flathub"
            }),
        )
        .unwrap();
        assert_eq!(spec.action_name, "InstallFlatpak");
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "flatpak".to_string(),
                    "alice".to_string(),
                    "install".to_string(),
                    "--user".to_string(),
                    "-y".to_string(),
                    "flathub".to_string(),
                    "org.mozilla.firefox".to_string(),
                ],
            }
        );
    }

    #[test]
    fn build_spec_pin_deployment_injects_index() {
        let spec = build_action_spec("PinDeployment", &json!({ "index": 1 })).unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "ostree".to_string(),
                    "admin".to_string(),
                    "pin".to_string(),
                    "1".to_string()
                ],
            }
        );
    }

    #[test]
    fn build_spec_unpin_deployment_includes_unpin_flag() {
        let spec = build_action_spec("UnpinDeployment", &json!({ "index": 2 })).unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "ostree".to_string(),
                    "admin".to_string(),
                    "pin".to_string(),
                    "--unpin".to_string(),
                    "2".to_string(),
                ],
            }
        );
    }

    #[test]
    fn require_u32_rejects_overflow() {
        let err = build_action_spec("PinDeployment", &json!({ "index": u64::MAX })).unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("index")),
            "expected InvalidParam(index), got: {err}"
        );
    }

    /// The root-owned helper `packaging/sysknife-action-steps` validates every
    /// rpm-ostree operand again, because it is reachable through sudo without the
    /// daemon. Both copies read `tests/data/rpm-ostree-parity.txt`; the helper's
    /// side is `class RpmOstreeVerb` in `tests/release/action-steps.test.sh`.
    #[test]
    fn rpm_ostree_parity_corpus_agrees_with_the_daemon_validators() {
        let corpus = include_str!("../tests/data/rpm-ostree-parity.txt");
        let mut seen: std::collections::BTreeSet<(String, String)> = Default::default();
        let mut checked = 0;
        for (index, line) in corpus.lines().enumerate() {
            let number = index + 1;
            if line.is_empty() || line.starts_with('#') {
                continue;
            }
            let mut parts = line.splitn(3, ' ');
            let (Some(kind), Some(verdict), Some(operand)) =
                (parts.next(), parts.next(), parts.next())
            else {
                panic!("corpus line {number} is not `<kind> <ok|refuse> <operand>`: {line:?}");
            };
            let accepted = match kind {
                "package" => validated_install_package(operand, "package").is_ok(),
                "ref" => validated_rebase_ref(operand, "target_ref").is_ok(),
                "append" => validated_safe_kernel_arg(operand, "add").is_ok(),
                "delete" => validated_safe_kernel_arg_removal(operand, "remove").is_ok(),
                other => panic!("corpus line {number}: unknown kind {other:?}"),
            };
            match verdict {
                "ok" => assert!(
                    accepted,
                    "corpus line {number}: `{kind} {operand}` must be accepted"
                ),
                "refuse" => assert!(
                    !accepted,
                    "corpus line {number}: `{kind} {operand}` must be refused"
                ),
                other => panic!("corpus line {number}: unknown verdict {other:?}"),
            }
            seen.insert((kind.to_string(), verdict.to_string()));
            checked += 1;
        }
        assert!(
            checked >= 60,
            "only {checked} corpus lines were checked; the corpus was truncated or not parsed"
        );
        for kind in ["package", "ref", "append", "delete"] {
            for verdict in ["ok", "refuse"] {
                assert!(
                    seen.contains(&(kind.to_string(), verdict.to_string())),
                    "the corpus has no `{kind} {verdict}` line, so that half is unchecked"
                );
            }
        }
    }

    #[test]
    fn rebase_system_refuses_a_local_source() {
        for target_ref in ["/tmp/repo", "ostree-unverified-image:oci:/tmp/img"] {
            let err = build_action_spec("RebaseSystem", &json!({ "target_ref": target_ref }))
                .unwrap_err();
            assert!(
                matches!(err, ExecutorError::InvalidParam("target_ref")),
                "{target_ref:?}: expected InvalidParam(target_ref), got: {err}"
            );
        }
    }

    #[test]
    fn build_spec_rebase_system_injects_target_ref() {
        let spec = build_action_spec(
            "RebaseSystem",
            &json!({ "target_ref": "fedora/41/x86_64/silverblue" }),
        )
        .unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "rpm-ostree".to_string(),
                    "rebase".to_string(),
                    "fedora/41/x86_64/silverblue".to_string(),
                ],
            }
        );
    }

    #[test]
    fn build_spec_set_kernel_arguments_appends_and_deletes() {
        let spec = build_action_spec(
            "SetKernelArguments",
            &json!({ "add": ["nomodeset"], "remove": ["quiet"] }),
        )
        .unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "rpm-ostree".to_string(),
                    "kargs".to_string(),
                    "append".to_string(),
                    "nomodeset".to_string(),
                    "delete".to_string(),
                    "quiet".to_string(),
                ],
            }
        );
    }

    #[test]
    fn build_spec_set_kernel_arguments_with_empty_arrays() {
        let spec =
            build_action_spec("SetKernelArguments", &json!({ "add": [], "remove": [] })).unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "rpm-ostree".to_string(),
                    "kargs".to_string(),
                ],
            }
        );
    }

    #[test]
    fn build_spec_set_kernel_arguments_defaults_when_keys_absent() {
        let spec = build_action_spec("SetKernelArguments", &json!({})).unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "rpm-ostree".to_string(),
                    "kargs".to_string(),
                ],
            }
        );
    }

    // ── Critical-account denylist (DeleteUser/DeleteGroup/LockUserAccount) ──

    #[test]
    fn delete_user_rejects_critical_account() {
        let err = build_action_spec("DeleteUser", &json!({ "username": "root" })).unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("username")),
            "expected InvalidParam(username), got: {err}"
        );
    }

    #[test]
    fn delete_group_rejects_critical_group() {
        let err = build_action_spec("DeleteGroup", &json!({ "group": "sudo" })).unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("group")),
            "expected InvalidParam(group), got: {err}"
        );
    }

    #[test]
    fn lock_user_account_rejects_critical_account() {
        let err = build_action_spec("LockUserAccount", &json!({ "username": "root" })).unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("username")),
            "expected InvalidParam(username), got: {err}"
        );
    }

    /// The helper behind UnlockUserAccount refuses critical accounts, as the
    /// lock path always has: unlocking a root account an administrator locked
    /// on purpose is the same decision made in reverse.
    #[test]
    fn unlock_user_account_rejects_critical_account() {
        let err =
            build_action_spec("UnlockUserAccount", &json!({ "username": "root" })).unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("username")),
            "expected InvalidParam(username), got: {err}"
        );
        assert!(build_action_spec("UnlockUserAccount", &json!({ "username": "alice" })).is_ok());
    }

    #[test]
    fn delete_user_lock_user_account_and_delete_group_allow_normal_names() {
        assert!(build_action_spec("DeleteUser", &json!({ "username": "alice" })).is_ok());
        assert!(build_action_spec("LockUserAccount", &json!({ "username": "alice" })).is_ok());
        assert!(build_action_spec("DeleteGroup", &json!({ "group": "developers" })).is_ok());
    }

    // ── execute_spec ──────────────────────────────────────────────────────

    #[test]
    fn build_spec_add_package_repository_rejects_path_traversal() {
        let err = build_action_spec(
            "AddPackageRepository",
            &json!({ "repo_id": "../cron.d/evil", "repo_url": "https://evil.example/repo" }),
        )
        .unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("repo_id")),
            "expected InvalidParam(repo_id), got: {err}"
        );
    }

    #[test]
    fn build_spec_add_package_repository_rejects_newline_in_url() {
        let err = build_action_spec(
            "AddPackageRepository",
            &json!({ "repo_id": "myrepo", "repo_url": "https://ok.example/\nbaseurl=evil" }),
        )
        .unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("repo_url")),
            "expected InvalidParam(repo_url), got: {err}"
        );
    }

    #[test]
    fn build_spec_add_package_repository_accepts_valid_repo_id() {
        let spec = build_action_spec(
            "AddPackageRepository",
            &json!({ "repo_id": "my-repo_123", "repo_url": "https://ok.example/repo" }),
        )
        .unwrap();
        assert_eq!(spec.action_name, "AddPackageRepository");
    }

    #[test]
    fn build_spec_remove_package_repository_rejects_path_traversal() {
        let err = build_action_spec(
            "RemovePackageRepository",
            &json!({ "repo_id": "../../etc/passwd" }),
        )
        .unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("repo_id")),
            "expected InvalidParam(repo_id), got: {err}"
        );
    }

    #[tokio::test]
    async fn execute_spec_command_captures_stdout() {
        let spec = ActionSpec {
            action_name: "GetSystemState",
            mechanism: ActionMechanism::Command {
                program: "echo",
                args: vec!["hello".to_string()],
            },
            risk_level: RiskLevel::Low,
            reboot_required: false,
            rollback_available: false,
        };
        let out = execute_spec(&spec).await.unwrap();
        assert_eq!(out.stdout.trim(), "hello");
        assert_eq!(out.exit_code, 0);
    }

    /// Regression guard for the live subprocess stdout relay. This coverage
    /// previously lived in the dispatcher (`stream_command_sends_job_progress_
    /// lines_during_execution`) and was lost when the streaming code moved here;
    /// The `ActionNotStopped` message is what an operator reads in the job
    /// summary, and the dispatcher keys the rollback veto off this variant, so
    /// its fields and wording are load-bearing. No integration test constructs
    /// it (the real path needs a root child), so pin it directly.
    #[test]
    fn action_not_stopped_names_the_group_and_the_timeout() {
        let err = ExecutorError::ActionNotStopped {
            program: "rpm-ostree".to_string(),
            pgid: 4242,
            timeout_secs: 7200,
        };
        let msg = err.to_string();
        assert!(msg.contains("4242"), "must name the pgid to inspect: {msg}");
        assert!(msg.contains("7200"), "must name the timeout: {msg}");
        assert!(
            msg.contains("could not be confirmed stopped"),
            "must say what happened: {msg}"
        );
        assert!(
            msg.contains("rollback was skipped"),
            "must say the rollback was skipped: {msg}"
        );
    }

    /// A same-uid group is genuinely killable, so `kill_and_reap` must return the
    /// plain stopped-timeout `Io`, not `ActionNotStopped`. This pins the
    /// discrimination the variant exists for, and that the function returns
    /// promptly rather than hanging on the reap.
    #[tokio::test]
    async fn kill_and_reap_confirms_a_killable_group_stopped_and_returns_bounded() {
        let mut child = tokio::process::Command::new("sh")
            .args(["-c", "sleep 3600 & wait"])
            .process_group(0)
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .spawn()
            .expect("spawn");
        SUDO_INVOCATIONS.store(0, std::sync::atomic::Ordering::SeqCst);
        let started = tokio::time::Instant::now();
        let err = kill_and_reap(&mut child, "sh", &[], StopCause::Timeout).await;
        let elapsed = started.elapsed();

        assert!(
            matches!(&err, ExecutorError::Io(e) if e.kind() == io::ErrorKind::TimedOut),
            "a killable group must report a plain stopped-timeout, got: {err:?}"
        );
        assert!(
            elapsed < Duration::from_secs(GROUP_TERM_GRACE.as_secs() + 3),
            "must return promptly, took {elapsed:?}"
        );
        // A same-uid group is killed by the daemon's own signals, so the
        // privileged escalation must NOT fire (a mutation that always escalates
        // would shell out to sudo and trip this).
        assert_eq!(
            SUDO_INVOCATIONS.load(std::sync::atomic::Ordering::SeqCst),
            0,
            "a killable group must not escalate to the privileged reaper"
        );
    }

    /// Losing the ability to READ a privileged child must stop it, exactly as a
    /// timeout does. `lines()` fails with `InvalidData` on non-UTF-8 stdout —
    /// reachable from any action whose output carries a byte sequence that is not
    /// valid UTF-8 (a filename in a foreign encoding is enough). Returning that
    /// error without reaping leaves a root process group running while the
    /// executor reports the action failed, so the dispatcher's rollback starts a
    /// second privileged transaction on top of the first.
    #[tokio::test]
    async fn a_child_that_outlives_a_stdout_read_failure_is_stopped_not_orphaned() {
        let dir = tempfile::tempdir().expect("tempdir");
        let pgid_file = dir.path().join("pgid");
        // `process_group(0)` makes the shell its own group leader, so `$$` IS the
        // pgid. It prints one good line, then a lone \377 (never valid UTF-8),
        // then outlives the read failure unless the executor stops it.
        let script = format!(
            "echo $$ > {}; echo started; printf '\\377\\n'; sleep 3600",
            pgid_file.display()
        );
        let (tx, _rx) = tokio::sync::mpsc::unbounded_channel();
        let err = execute_command_with_progress("sh", &["-c".to_string(), script], tx)
            .await
            .expect_err("non-UTF-8 stdout must fail the action");
        assert!(
            matches!(&err, ExecutorError::Io(e) if e.kind() == io::ErrorKind::InvalidData),
            "the read failure itself must be surfaced, got: {err:?}"
        );

        let pgid: i32 = std::fs::read_to_string(&pgid_file)
            .expect("the shell must have recorded its pgid")
            .trim()
            .parse()
            .expect("pgid");
        assert!(
            probe_group(pgid).is_gone(),
            "process group {pgid} survived the read failure; \
             the privileged child was orphaned"
        );
    }

    #[test]
    fn reap_command_cancels_rpm_ostree_but_group_kills_everything_else() {
        // rpm-ostree -> cancel (its work is in another cgroup, a signal can't reach it).
        assert_eq!(
            reap_command(
                99,
                "sudo",
                &["/usr/bin/rpm-ostree".to_string(), "upgrade".to_string()]
            ),
            vec!["-n", "/usr/bin/rpm-ostree", "cancel"]
        );
        // Everything else -> a root TERM to its own process group.
        assert_eq!(
            reap_command(
                99,
                "sudo",
                &[
                    "env".to_string(),
                    "apt-get".to_string(),
                    "install".to_string()
                ]
            ),
            root_group_kill_argv("TERM", 99)
        );
    }

    /// The operand-taking rpm-ostree actions moved behind `action-steps
    /// rpm-ostree`, and the transaction still runs in rpm-ostreed's cgroup, so a
    /// timed-out one must still be cancelled rather than group-killed.
    /// tests/sudoers_grants_match_argv.rs checks a grant admits the cancel argv.
    #[test]
    fn reap_command_still_cancels_an_rpm_ostree_action_behind_the_helper() {
        for name in [
            "AddLayeredPackage",
            "InstallPackages",
            "RemovePackages",
            "RemoveLayeredPackage",
            "ReplaceLayeredPackage",
            "RemoveBasePackage",
            "RebaseSystem",
            "SetKernelArguments",
        ] {
            let params = match name {
                "InstallPackages" | "RemovePackages" => json!({"packages": ["vim"]}),
                "ReplaceLayeredPackage" => json!({"old": "vim", "new": "nano"}),
                "RebaseSystem" => json!({"target_ref": "fedora:fedora/41/x86_64/silverblue"}),
                "SetKernelArguments" => json!({"add": ["quiet"]}),
                _ => json!({"package": "vim"}),
            };
            let spec = build_action_spec(name, &params).unwrap();
            let ActionMechanism::Command { program, args } = &spec.mechanism else {
                panic!("{name} is not a command");
            };
            assert_eq!(
                args[0], "/usr/lib/sysknife/action-steps",
                "{name}: {args:?}"
            );
            assert_eq!(
                reap_command(99, program, args),
                vec!["-n", "/usr/bin/rpm-ostree", "cancel"],
                "{name} would be group-killed while its transaction runs on"
            );
        }
    }

    #[test]
    fn root_group_kill_argv_targets_the_whole_group_non_interactively() {
        // sudo -n action-steps signal KILL -<pgid>: non-interactive
        // (NOPASSWD). tests/sudoers_grants_match_argv.rs holds REAPER_ARGV,
        // the same argv, and fails if no grant admits it.
        assert_eq!(
            root_group_kill_argv("KILL", 4242),
            vec![
                "-n",
                "/usr/lib/sysknife/action-steps",
                "signal",
                "KILL",
                "-4242"
            ]
        );
        assert_eq!(
            root_group_kill_argv("TERM", 7)[3..].to_vec(),
            vec!["TERM", "-7"]
        );
    }

    #[test]
    fn is_rpm_ostree_action_detects_the_transaction_client_behind_sudo() {
        let sudo = |a: &[&str]| {
            is_rpm_ostree_action("sudo", &a.iter().map(|s| s.to_string()).collect::<Vec<_>>())
        };
        // rpm-ostree runs behind sudo, absolute or bare, and directly.
        assert!(sudo(&["/usr/bin/rpm-ostree", "upgrade"]));
        assert!(sudo(&[
            "rpm-ostree",
            "rebase",
            "fedora:fedora/40/x86_64/silverblue"
        ]));
        assert!(is_rpm_ostree_action("rpm-ostree", &["status".to_string()]));
        // Package managers whose work IS in the process group must NOT be
        // treated as rpm-ostree (they get the group kill, not `cancel`).
        assert!(!sudo(&[
            "env",
            "DEBIAN_FRONTEND=noninteractive",
            "apt-get",
            "install",
            "vim"
        ]));
        assert!(!sudo(&["/usr/bin/kill", "-s", "KILL", "--", "-1"]));
        assert!(!is_rpm_ostree_action("sudo", &[]));
        // Absolute path as the top-level program (no sudo wrapper).
        assert!(is_rpm_ostree_action(
            "/usr/bin/rpm-ostree",
            &["deploy".to_string()]
        ));
        // A path segment must match, not a substring (guards a future refactor
        // to `.contains()`).
        assert!(!is_rpm_ostree_action(
            "sudo",
            &["explain-rpm-ostree-usage".to_string()]
        ));
    }

    /// restored at its owning layer. Proves `RealActionExecutor` forwards each
    /// stdout line over the mpsc channel as it arrives and reports the exit code.
    #[tokio::test]
    async fn real_executor_streams_each_stdout_line() {
        let spec = ActionSpec {
            action_name: "GetSystemState",
            mechanism: ActionMechanism::Command {
                program: "printf",
                args: vec!["line-one\\nline-two\\nline-three\\n".to_string()],
            },
            risk_level: RiskLevel::Low,
            reboot_required: false,
            rollback_available: false,
        };
        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
        let out = RealActionExecutor
            .execute_with_progress(&spec, tx)
            .await
            .unwrap();

        let mut lines = Vec::new();
        while let Ok(line) = rx.try_recv() {
            lines.push(line);
        }
        assert_eq!(lines, vec!["line-one", "line-two", "line-three"]);
        assert_eq!(out.exit_code, 0);
        assert!(out.stdout.contains("line-two"));
    }

    #[tokio::test]
    async fn execute_spec_file_write_creates_file() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("test.conf").to_string_lossy().into_owned();
        let spec = ActionSpec {
            action_name: "AddPackageRepository",
            mechanism: ActionMechanism::FileWrite {
                path: path.clone(),
                content: "[repo]\nbaseurl=https://example.test\n".to_string(),
            },
            risk_level: RiskLevel::Medium,
            reboot_required: false,
            rollback_available: true,
        };
        let out = execute_spec(&spec).await.unwrap();
        assert_eq!(out.exit_code, 0);
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            "[repo]\nbaseurl=https://example.test\n"
        );
    }

    #[tokio::test]
    async fn execute_spec_file_patch_replaces_first_occurrence() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("repo.conf").to_string_lossy().into_owned();
        std::fs::write(&path, "[myrepo]\nenabled=0\n").unwrap();
        let spec = ActionSpec {
            action_name: "EnablePackageRepository",
            mechanism: ActionMechanism::FilePatch {
                path: path.clone(),
                search: "enabled=0".to_string(),
                replace: "enabled=1".to_string(),
            },
            risk_level: RiskLevel::Medium,
            reboot_required: false,
            rollback_available: true,
        };
        execute_spec(&spec).await.unwrap();
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            "[myrepo]\nenabled=1\n"
        );
    }

    #[tokio::test]
    async fn execute_spec_file_patch_returns_error_when_search_not_found() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("repo.conf").to_string_lossy().into_owned();
        std::fs::write(&path, "[myrepo]\nenabled=1\n").unwrap();
        let spec = ActionSpec {
            action_name: "EnablePackageRepository",
            mechanism: ActionMechanism::FilePatch {
                path: path.clone(),
                search: "enabled=0".to_string(),
                replace: "enabled=1".to_string(),
            },
            risk_level: RiskLevel::Medium,
            reboot_required: false,
            rollback_available: true,
        };
        let out = execute_spec(&spec).await.unwrap();
        assert_eq!(out.exit_code, 1, "should fail when search string is absent");
        assert!(
            out.stderr.contains("search string not found in file"),
            "stderr should explain the failure: {}",
            out.stderr
        );
        // File should remain unchanged.
        assert_eq!(
            std::fs::read_to_string(&path).unwrap(),
            "[myrepo]\nenabled=1\n"
        );
    }

    #[tokio::test]
    async fn execute_spec_file_patch_allows_empty_search_string() {
        // An empty search string triggers replacen's prepend behavior and should
        // not be rejected — the caller explicitly asked for a no-op search.
        let dir = tempdir().unwrap();
        let path = dir.path().join("file.txt").to_string_lossy().into_owned();
        std::fs::write(&path, "hello").unwrap();
        let spec = ActionSpec {
            action_name: "Test",
            mechanism: ActionMechanism::FilePatch {
                path: path.clone(),
                search: String::new(),
                replace: "prefix-".to_string(),
            },
            risk_level: RiskLevel::Low,
            reboot_required: false,
            rollback_available: false,
        };
        let out = execute_spec(&spec).await.unwrap();
        assert_eq!(out.exit_code, 0);
        assert_eq!(std::fs::read_to_string(&path).unwrap(), "prefix-hello");
    }

    #[tokio::test]
    async fn execute_spec_file_delete_removes_file() {
        let dir = tempdir().unwrap();
        let path = dir.path().join("repo.conf").to_string_lossy().into_owned();
        std::fs::write(&path, "[myrepo]\n").unwrap();
        let spec = ActionSpec {
            action_name: "RemovePackageRepository",
            mechanism: ActionMechanism::FileDelete { path: path.clone() },
            risk_level: RiskLevel::Medium,
            reboot_required: false,
            rollback_available: true,
        };
        execute_spec(&spec).await.unwrap();
        assert!(!std::path::Path::new(&path).exists());
    }

    #[tokio::test]
    async fn execute_spec_file_scan_lists_directory_entries() {
        let dir = tempdir().unwrap();
        std::fs::write(dir.path().join("a.repo"), "[a]\n").unwrap();
        std::fs::write(dir.path().join("b.repo"), "[b]\n").unwrap();
        let spec = ActionSpec {
            action_name: "ListPackageRepositories",
            mechanism: ActionMechanism::FileScan {
                path: dir.path().to_string_lossy().into_owned(),
            },
            risk_level: RiskLevel::Low,
            reboot_required: false,
            rollback_available: false,
        };
        let out = execute_spec(&spec).await.unwrap();
        assert!(
            out.stdout.contains("a.repo"),
            "expected a.repo in: {}",
            out.stdout
        );
        assert!(
            out.stdout.contains("b.repo"),
            "expected b.repo in: {}",
            out.stdout
        );
        assert_eq!(out.exit_code, 0);
    }

    // ── rollback_spec_for ─────────────────────────────────────────────────────

    #[test]
    fn rollback_spec_for_update_system_is_rpm_ostree_rollback() {
        let spec = rollback_spec_for("UpdateSystem").unwrap();
        assert_eq!(spec.action_name, "RollbackDeployment");
        assert!(
            matches!(
                &spec.mechanism,
                ActionMechanism::Command { program: "rpm-ostree", args }
                if args == &["rollback".to_string()]
            ),
            "expected rpm-ostree rollback, got: {:?}",
            spec.mechanism
        );
        assert!(!spec.rollback_available, "rollback spec must not recurse");
    }

    #[test]
    fn rollback_spec_for_install_packages_is_rpm_ostree_rollback() {
        assert!(rollback_spec_for("InstallPackages").is_some());
    }

    #[test]
    fn rollback_spec_for_remove_packages_is_rpm_ostree_rollback() {
        assert!(rollback_spec_for("RemovePackages").is_some());
    }

    #[test]
    fn rollback_spec_for_rebase_system_is_rpm_ostree_rollback() {
        assert!(rollback_spec_for("RebaseSystem").is_some());
    }

    #[test]
    fn rollback_spec_for_set_kernel_arguments_is_rpm_ostree_rollback() {
        assert!(rollback_spec_for("SetKernelArguments").is_some());
    }

    #[test]
    fn rollback_spec_for_read_only_action_returns_none() {
        assert!(rollback_spec_for("GetSystemState").is_none());
        assert!(rollback_spec_for("ListUsers").is_none());
        assert!(rollback_spec_for("GetFirewallState").is_none());
    }

    #[test]
    fn rollback_spec_for_non_rollbackable_actions_return_none() {
        assert!(rollback_spec_for("AddUserToGroup").is_none());
        assert!(rollback_spec_for("DeleteUser").is_none());
        assert!(rollback_spec_for("CleanupDeployments").is_none());
        // No infinite recursion — RollbackDeployment has no rollback of its own
        assert!(rollback_spec_for("RollbackDeployment").is_none());
    }

    // ── validated_public_key ──────────────────────────────────────────────

    #[test]
    fn public_key_accepts_valid_ed25519() {
        let key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host";
        assert!(validated_public_key(key).is_ok());
    }

    #[test]
    fn public_key_accepts_valid_rsa() {
        let key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCtest user@host";
        assert!(validated_public_key(key).is_ok());
    }

    #[test]
    fn public_key_rejects_empty() {
        assert!(matches!(
            validated_public_key(""),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
    }

    #[test]
    fn public_key_rejects_unknown_prefix() {
        assert!(matches!(
            validated_public_key("sk-rsa AAAA... user@host"),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
        assert!(matches!(
            validated_public_key("AAAAB3Nz... user@host"),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
    }

    #[test]
    fn public_key_rejects_single_quote() {
        let key = "ssh-ed25519 AAAA' $(rm -rf /) user@host";
        assert!(matches!(
            validated_public_key(key),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
    }

    /// The install/remove package actions must refuse a filesystem path, because
    /// `apt-get install /tmp/x.deb` / `rpm-ostree install /tmp/x.rpm` install a
    /// local file and run its scripts as root. `validate.rs` proves the validator
    /// refuses paths; only this proves each action arm actually calls it. Table
    /// driven so an arm added later that forgets the validator fails here, which
    /// is exactly the regression that shipped `InstallPackages`/`RemovePackages`
    /// on the generic safe-arg by mistake.
    #[test]
    fn package_actions_reject_a_local_file_target() {
        let reject: &[(&str, serde_json::Value)] = &[
            ("AptInstall", json!({"package": "/tmp/evil.deb"})),
            ("AptRemove", json!({"package": "/tmp/evil.deb"})),
            ("AptPurge", json!({"package": "./evil.deb"})),
            ("AptHold", json!({"package": "/tmp/evil.deb"})),
            ("AptUnhold", json!({"package": "/tmp/evil.deb"})),
            ("AddLayeredPackage", json!({"package": "/tmp/evil.rpm"})),
            ("RemoveLayeredPackage", json!({"package": "/tmp/evil.rpm"})),
            ("RemoveBasePackage", json!({"package": "/tmp/evil.rpm"})),
            (
                "ReplaceLayeredPackage",
                json!({"old": "/tmp/evil.rpm", "new": "nginx"}),
            ),
            (
                "ReplaceLayeredPackage",
                json!({"old": "nginx", "new": "/tmp/evil.rpm"}),
            ),
            ("InstallPackages", json!({"packages": ["/tmp/evil.rpm"]})),
            ("RemovePackages", json!({"packages": ["/tmp/evil.rpm"]})),
        ];
        for (action, params) in reject {
            assert!(
                matches!(
                    build_action_spec(action, params),
                    Err(ExecutorError::InvalidParam(_))
                ),
                "{action} must refuse a local-file package target: {params}"
            );
        }
        // Positive twin: real package specs must still build, or the test above
        // would pass for a validator that rejects everything.
        let accept: &[(&str, serde_json::Value)] = &[
            ("AptInstall", json!({"package": "nginx"})),
            ("AddLayeredPackage", json!({"package": "nginx=1.24.0-1"})),
            (
                "InstallPackages",
                json!({"packages": ["nginx", "python3-pip"]}),
            ),
        ];
        for (action, params) in accept {
            assert!(
                build_action_spec(action, params).is_ok(),
                "{action} must accept a real package spec: {params}"
            );
        }
    }

    /// apt-get reads the last character of an operand: `pkg-` on `install` removes
    /// the package, `pkg+` on `remove` or `purge` installs it, and `pkg^` installs a
    /// task. The validators refuse all three; only this proves every apt arm
    /// actually calls the right one, so an arm that goes back to the install
    /// validator fails here.
    #[test]
    fn apt_package_actions_refuse_a_trailing_modifier() {
        let reject: &[(&str, &str)] = &[
            ("AptInstall", "linux-image-generic-"),
            ("AptInstall", "nginx-"),
            ("AptRemove", "nginx-"),
            ("AptRemove", "nginx+"),
            ("AptRemove", "g++"),
            ("AptPurge", "nginx-"),
            ("AptPurge", "linux-image-generic+"),
            ("AptHold", "nginx-"),
            ("AptHold", "nginx+"),
            ("AptUnhold", "nginx-"),
            ("AptUnhold", "nginx+"),
            ("AptShow", "nginx-"),
            // A trailing `^` installs every package of a task.
            ("AptInstall", "ubuntu-desktop^"),
            ("AptRemove", "ubuntu-desktop^"),
            ("AptPurge", "ubuntu-desktop^"),
            ("AptHold", "ubuntu-desktop^"),
            ("AptUnhold", "ubuntu-desktop^"),
            ("AptShow", "ubuntu-desktop^"),
        ];
        for (action, package) in reject {
            let result = build_action_spec(action, &json!({ "package": package }));
            assert!(
                matches!(result, Err(ExecutorError::InvalidParam("package"))),
                "{action} {package:?} must be refused, got {result:?}"
            );
        }
        // Positive twins, so the table above cannot pass for a validator that
        // refuses everything. `g++` and `libstdc++6` must stay installable.
        let accept: &[(&str, &str)] = &[
            ("AptInstall", "g++"),
            ("AptInstall", "libstdc++6"),
            ("AptInstall", "nginx+"),
            ("AptRemove", "libstdc++6"),
            ("AptRemove", "g++:amd64"),
            ("AptPurge", "g++:amd64"),
            ("AptHold", "libstdc++6"),
            ("AptUnhold", "libstdc++6"),
            ("AptShow", "g++"),
            ("AptShow", "nginx/noble"),
        ];
        for (action, package) in accept {
            assert!(
                build_action_spec(action, &json!({ "package": package })).is_ok(),
                "{action} {package:?} must be accepted"
            );
        }
    }

    /// The activation verbs must refuse a root-shell unit through the reachable
    /// action, and `SetServiceEnabled` must gate only on `enabled: true`. Mutation
    /// testing showed reverting these call sites to the loose validator passed the
    /// whole suite, so the denylist was pinned only at the validator, not here.
    #[test]
    fn activating_actions_refuse_a_root_shell_unit() {
        for action in ["StartService", "RestartService", "UnmaskService"] {
            for unit in [
                "debug-shell.service",
                "emergency.target",
                "rescue.service",
                "runlevel1.target",
            ] {
                assert!(
                    matches!(
                        build_action_spec(action, &json!({"unit": unit})),
                        Err(ExecutorError::InvalidParam("unit"))
                    ),
                    "{action} must not activate {unit}"
                );
            }
            assert!(
                build_action_spec(action, &json!({"unit": "nginx.service"})).is_ok(),
                "{action} must still activate an ordinary unit"
            );
        }
        assert!(
            build_action_spec(
                "SetServiceEnabled",
                &json!({"unit": "debug-shell.service", "enabled": true})
            )
            .is_err(),
            "enabling a root-shell unit brings it up at boot and must be refused"
        );
        assert!(
            build_action_spec(
                "SetServiceEnabled",
                &json!({"unit": "debug-shell.service", "enabled": false})
            )
            .is_ok(),
            "disabling a root-shell unit is a mitigation and must stay reachable"
        );
        // The safe verbs must not have been tightened into the denylist, or an
        // operator loses the ability to stop or mask a running root shell.
        for action in ["StopService", "MaskService"] {
            assert!(
                build_action_spec(action, &json!({"unit": "debug-shell.service"})).is_ok(),
                "{action} on debug-shell is a mitigation and must stay allowed"
            );
        }
    }

    #[test]
    fn authorized_keys_actions_reject_a_traversal_username() {
        // `actions/ssh.rs` builds `/home/{username}/.ssh/authorized_keys` by
        // interpolation, so the only thing keeping the path inside the user's
        // home is `validated_username` being called in these three match arms.
        // `validate.rs` tests the validator in isolation, and `ssh_key_ops.rs`
        // calls the action functions directly — neither proves the guard is
        // actually wired to the reachable actions.
        for action in [
            "GetAuthorizedKeys",
            "AddAuthorizedKey",
            "RemoveAuthorizedKey",
        ] {
            for bad in ["../../etc", "..", "root/../../etc"] {
                let mut params = json!({"username": bad});
                if action != "GetAuthorizedKeys" {
                    params["public_key"] =
                        json!("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample u@h");
                }
                let err = build_action_spec(action, &params).unwrap_err();
                assert!(
                    matches!(err, ExecutorError::InvalidParam("username")),
                    "{action} must reject username {bad:?}, got {err:?}"
                );
            }
        }
    }

    #[test]
    fn ip_taking_actions_reject_a_malformed_address() {
        // `ExecutorError::InvalidIpAddress` was constructed by three actions
        // and reached by no test.
        let cases: [(&str, serde_json::Value); 3] = [
            (
                "ResolvectlSetDns",
                json!({ "interface": "eth0", "servers": ["not-an-ip"] }),
            ),
            (
                "Fail2banBanIp",
                json!({ "jail": "sshd", "ip": "999.1.1.1" }),
            ),
            (
                "Fail2banUnbanIp",
                json!({ "jail": "sshd", "ip": "1.2.3.4.5" }),
            ),
        ];
        for (action, params) in cases {
            let err = build_action_spec(action, &params).unwrap_err();
            assert!(
                matches!(err, ExecutorError::InvalidIpAddress { .. }),
                "{action} must reject a malformed IP, got {err:?}"
            );
        }
    }

    #[test]
    fn public_key_rejects_pipe_metacharacter() {
        // '|' is a shell pipe and never appears in a valid key. (It was also
        // the sed address delimiter before the key ops were made regex-free;
        // the rejection stands on its own merits either way.)
        let key = "ssh-ed25519 AAAA|; rm -rf /etc user@host";
        assert!(matches!(
            validated_public_key(key),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
    }

    #[test]
    fn public_key_accepts_regex_metacharacters_so_consumers_must_not_use_regex() {
        // Deliberate and load-bearing: `.` is legal inside a key comment
        // (`alice@example.com`), so the validator cannot blocklist regex
        // metacharacters without rejecting valid keys. Any consumer that
        // interprets a key as a pattern is therefore the defect — see
        // `actions::ssh::REMOVE_KEY_SCRIPT`, which uses `grep -Fxv` for
        // exactly this reason.
        let key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample alice@example.com";
        assert!(validated_public_key(key).is_ok());
        // The wildcard-shaped payload passes validation too. It is safe only
        // because no consumer treats it as a pattern.
        assert!(validated_public_key("ssh-ed25519 .*").is_ok());
    }

    #[test]
    fn public_key_rejects_shell_metacharacters() {
        for (metachar, desc) in [
            (';', "semicolon"),
            ('`', "backtick"),
            ('$', "dollar"),
            ('\\', "backslash"),
            ('&', "ampersand"),
        ] {
            let key = format!("ssh-ed25519 AAAA{metachar}injected user@host");
            assert!(
                matches!(
                    validated_public_key(&key),
                    Err(ExecutorError::InvalidParam("public_key"))
                ),
                "{desc} should be rejected"
            );
        }
    }

    #[test]
    fn public_key_rejects_newline() {
        let key = "ssh-ed25519 AAAA\nmalicious: line user@host";
        assert!(matches!(
            validated_public_key(key),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
        let key_cr = "ssh-ed25519 AAAA\rmalicious: line user@host";
        assert!(matches!(
            validated_public_key(key_cr),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
    }

    #[test]
    fn public_key_rejects_too_long() {
        // Build a key that exceeds MAX_LEN (8192 bytes)
        let long_payload = "A".repeat(8192);
        let key = format!("ssh-ed25519 {long_payload} user@host");
        assert!(matches!(
            validated_public_key(&key),
            Err(ExecutorError::InvalidParam("public_key"))
        ));
    }

    // ── str_array_or_empty ────────────────────────────────────────────────

    #[test]
    fn str_array_or_empty_rejects_non_string_element() {
        let params = json!({ "packages": ["vim", 42, "curl"] });
        assert!(matches!(
            str_array_or_empty(&params, "packages"),
            Err(ExecutorError::InvalidParam("packages"))
        ));
    }

    #[test]
    fn str_array_or_empty_accepts_string_array() {
        let params = json!({ "packages": ["vim", "curl"] });
        assert_eq!(
            str_array_or_empty(&params, "packages").unwrap(),
            vec!["vim".to_string(), "curl".to_string()]
        );
    }

    #[test]
    fn str_array_or_empty_returns_empty_when_key_absent() {
        let params = json!({});
        assert_eq!(
            str_array_or_empty(&params, "packages").unwrap(),
            Vec::<String>::new()
        );
    }

    // ── validated_safe_kernel_arg ─────────────────────────────────────────

    #[test]
    fn kernel_arg_allows_safe_args() {
        assert!(validated_safe_kernel_arg("quiet", "add").is_ok());
        assert!(validated_safe_kernel_arg("splash", "add").is_ok());
        assert!(validated_safe_kernel_arg("rd.driver.blacklist=nouveau", "add").is_ok());
        assert!(validated_safe_kernel_arg("console=ttyS0,115200", "add").is_ok());
    }

    #[test]
    fn kernel_arg_blocks_init_override() {
        assert!(matches!(
            validated_safe_kernel_arg("init=/bin/sh", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("INIT=/sbin/bash", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_selinux_disable() {
        assert!(matches!(
            validated_safe_kernel_arg("selinux=0", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("enforcing=0", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_security_override() {
        assert!(matches!(
            validated_safe_kernel_arg("security=none", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_module_blacklist() {
        assert!(matches!(
            validated_safe_kernel_arg("module_blacklist=dm_crypt", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    // ── validated_safe_kernel_arg_removal ─────────────────────────────────
    //
    // "Removing an argument is always safe" was the stated premise for exempting
    // `remove`/`delete` from any policy check. It is false: several arguments
    // protect the host by being PRESENT, so deleting one lands the same end state
    // as adding its weakening counterpart, which the add-path already refuses.

    #[test]
    fn kernel_arg_removal_blocks_stripping_a_hardening_arg() {
        // KSPP-recommended boot parameters plus the LSM selectors. Each is a
        // protection the host loses the moment the token leaves the boot line.
        for arg in [
            "lockdown=confidentiality",
            "module.sig_enforce=1",
            "selinux=1",
            "enforcing=1",
            "apparmor=1",
            "security=selinux",
            "pti=on",
            "mitigations=auto,nosmt",
            "init_on_alloc=1",
            "init_on_free=1",
            "slab_nomerge",
            "page_alloc.shuffle=1",
            "randomize_kstack_offset=on",
            "slub_debug=FZP",
            "vsyscall=none",
            "debugfs=off",
            "iommu=force",
            "intel_iommu=on",
            "amd_iommu=force_isolation",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg_removal(arg, "remove"),
                    Err(ExecutorError::InvalidParam("remove"))
                ),
                "removing {arg} is a boot-security downgrade and must be refused"
            );
        }
    }

    /// The screens accept a fixed list of keys. Four review rounds of the
    /// denylist this replaced each found another spelling past it (a hyphen in
    /// the key, a `kstrtobool` prefix such as `of`, a mitigation switch nobody
    /// had listed), so anything not named is refused, with an error that names
    /// the parameter.
    #[test]
    fn kernel_arg_add_accepts_only_the_allowlist() {
        for arg in [
            "quiet",
            "splash",
            "rhgb",
            "nomodeset",
            "nowatchdog",
            "threadirqs",
            "nosmt",
            "slab_nomerge",
            "console=ttyS0,115200",
            "rd.driver.blacklist=nouveau",
            "transparent_hugepage=madvise",
            "nvidia-drm.modeset=1",
            "lockdown=integrity",
            "lockdown=confidentiality",
            "module.sig_enforce=1",
            "intel_iommu=on",
            "amd_iommu=force_isolation",
            "init_on_alloc=1",
            "init_on_free=1",
            "page_alloc.shuffle=1",
            "randomize_kstack_offset=on",
            "mitigations=auto",
            "mitigations=auto,nosmt",
            "pti=on",
            "vsyscall=none",
            "debugfs=off",
            "QUIET",
        ] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_ok(),
                "{arg} is on the allowlist and must be accepted"
            );
        }
        for arg in [
            // The review rounds' bypass spellings.
            "spectre-v2=off",
            "audit=off",
            "systemd.wants=debug-shell.service",
            "lsm=landlock",
            "mitigations=of",
            "nopku",
            "spectre_v2_user=off",
            "kpti=0",
            "its=off",
            "tsa=off",
            "vmscape=off",
            "noibrs",
            "noibpb",
            "audit=f",
            // Unknown keys, a flag given a value, an empty value, a value off the list.
            "foo=bar",
            "foo",
            "root=/dev/sdb1",
            "quiet=1",
            "console=",
            "lockdown=none",
            "mitigations=off",
            "mitigations=auto,nosmt,foo",
            "module.sig_enforce=0",
            "debugfs=on",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg(arg, "add"),
                    Err(ExecutorError::InvalidParam("add"))
                ),
                "{arg} is not on the allowlist and must be refused, naming `add`"
            );
        }
    }

    /// `resume=` at a device the caller controls boots a crafted hibernation
    /// image, so it is not on the list (this test's `resume=/dev/mapper/luks-swap`
    /// used to be accepted as an ordinary token). `rd.driver.blacklist=` takes
    /// only GPU drivers, each comma-separated value from its own set, so
    /// `tpm_crb` or `dm_crypt` cannot be kept from loading.
    #[test]
    fn kernel_arg_add_refuses_resume_and_limits_the_driver_blacklist() {
        for arg in [
            "resume=/dev/sdb1",
            "resume=/dev/mapper/luks-swap",
            "resume_offset=1",
            "rd.driver.blacklist=tpm_crb",
            "rd.driver.blacklist=nouveau,dm_crypt",
            "rd.driver.blacklist=",
            "rd.driver.blacklist=nouveau,",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg(arg, "add"),
                    Err(ExecutorError::InvalidParam("add"))
                ),
                "{arg} must be refused"
            );
        }
        for arg in [
            "rd.driver.blacklist=nouveau",
            "rd.driver.blacklist=nouveau,nvidia,nvidia_drm,nvidia_modeset",
            "rd.driver.blacklist=radeon,amdgpu,i915",
        ] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_ok(),
                "{arg} must be accepted"
            );
        }
        for arg in ["resume", "resume=/dev/mapper/luks-swap", "resume_offset"] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_err(),
                "{arg} is not on the allowlist, so removing it is refused"
            );
        }
        assert!(validated_safe_kernel_arg_removal("rd.driver.blacklist=nouveau", "remove").is_ok());
    }

    /// Removal is allowed for the ordinary keys of the allowlist and for the
    /// exact downgrades in KARG_WEAKENING, and refused for a hardening key
    /// (bare or with a value) and for any key nobody listed.
    #[test]
    fn kernel_arg_remove_accepts_only_ordinary_keys_and_known_downgrades() {
        for arg in [
            "quiet",
            "rhgb",
            "quiet=1",
            "console=ttyS0",
            "rd.driver.blacklist=nouveau",
            "mitigations=off",
            "init=/bin/sh",
            "single",
            "nokaslr",
            "spectre_v2=off",
        ] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_ok(),
                "{arg} must stay removable"
            );
        }
        for arg in [
            "lockdown",
            "module.sig_enforce",
            "lockdown=integrity",
            "nosmt",
            "slab_nomerge",
            "vsyscall=none",
            "mitigations=auto",
            "foo=bar",
            "foo",
            "mitigations=of",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg_removal(arg, "remove"),
                    Err(ExecutorError::InvalidParam("remove"))
                ),
                "removing {arg} must be refused, naming `remove`"
            );
        }
    }

    /// The kernel's `parameq()` (kernel/params.c) and systemd's
    /// `proc_cmdline_key_streq()` treat `-` and `_` as equal in a parameter
    /// name, so a hyphen spelling reaches the same switch an underscore-only
    /// list refuses. The value is not normalised: unit names keep their hyphens.
    #[test]
    fn kernel_arg_screens_treat_dash_and_underscore_alike_in_the_key() {
        for arg in [
            "spectre-v2=off",
            "module-blacklist=apparmor",
            "Spec-Store-Bypass-Disable=off",
            "systemd.debug-shell=1",
            "rd.systemd.debug-shell",
            "nospectre-v2",
            "nospectre-bhb",
            "tsx-async-abort=off",
        ] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_err(),
                "{arg} is an underscore switch spelled with hyphens and must be refused"
            );
        }
        for arg in [
            "module.sig-enforce=1",
            "init-on-alloc=1",
            "randomize-kstack-offset=on",
            "page-alloc.shuffle=1",
        ] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_err(),
                "{arg} is a protection spelled with hyphens and must not be removable"
            );
        }
        for arg in ["init-on-alloc=0", "module.sig-enforce=0"] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_ok(),
                "{arg} is a weakening spelled with hyphens and must stay removable"
            );
        }
        assert!(validated_safe_kernel_arg("systemd.unit=debug-shell.service", "add").is_err());
        // A listed key spelled with hyphens is the same key.
        assert!(validated_safe_kernel_arg("nvidia-drm.modeset=1", "add").is_ok());
    }

    /// Where the kernel reads a switch as a boolean or as `off`, every spelling
    /// of "off" turns it off, not only the one a list happened to name.
    #[test]
    fn kernel_arg_blocks_every_spelling_of_off_for_a_protection_switch() {
        for arg in [
            "audit=off",
            "audit=0",
            "audit=n",
            "audit=no",
            "audit=false",
            "AUDIT=OFF",
            "mitigations=false",
            "pti=no",
            "spectre_v2=n",
            "mds=off",
            "tsx_async_abort=off",
            "mmio_stale_data=off",
            "retbleed=off",
            "srbds=off",
            "l1tf=off",
            "spectre_bhi=off",
            "gather_data_sampling=off",
            "reg_file_data_sampling=off",
            "module.sig_enforce=no",
            "init_on_free=false",
            "nospec_store_bypass_disable",
            "nospectre_bhb",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg(arg, "add"),
                    Err(ExecutorError::InvalidParam("add"))
                ),
                "{arg} switches a protection off and must be refused"
            );
        }
        for arg in [
            "audit=1",
            "mds=full",
            "retbleed=auto",
            "l1tf=flush",
            "spectre_bhi=on",
        ] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_err(),
                "{arg} is not on the allowlist"
            );
        }
        for arg in ["mitigations=auto", "pti=on"] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_ok(),
                "{arg} must stay valid"
            );
        }
    }

    /// The mitigation switches the add screen now refuses turning off are
    /// protections on the remove side, and their off spellings stay removable.
    #[test]
    fn kernel_arg_removal_protects_the_mitigation_switches() {
        for arg in [
            "mds=full",
            "tsx_async_abort=full",
            "mmio_stale_data=full",
            "retbleed=auto",
            "srbds=on",
            "l1tf=flush",
            "spectre_bhi=on",
            "gather_data_sampling=force",
            "reg_file_data_sampling=on",
            "spectre_v2=on",
            "spec_store_bypass_disable=on",
            "mds",
        ] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_err(),
                "removing {arg} weakens the next boot and must be refused"
            );
        }
        for arg in ["mds=off", "retbleed=off", "spectre_v2=off"] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_ok(),
                "{arg} is a weakening, so removing it must stay allowed"
            );
        }
        // Only the exact spellings in KARG_WEAKENING are known downgrades.
        for arg in ["audit=false", "pti=no"] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_err(),
                "{arg} is not in KARG_WEAKENING"
            );
        }
    }

    /// libostree deletes a key's only value when asked for the bare key
    /// (`ostree_kernel_args_delete`, "for input arg with a single key ... the
    /// key/value pair will be deleted if there is only one value"), so
    /// `--delete=lockdown` removes `lockdown=confidentiality`. The prefix screen
    /// `lockdown=` never matched the bare `lockdown`.
    #[test]
    fn kernel_arg_removal_refuses_a_protective_bare_key() {
        for arg in [
            "lockdown",
            "module.sig_enforce",
            "selinux",
            "enforcing",
            "apparmor",
            "security",
            "iommu",
            "mitigations",
            "init_on_alloc",
            "lsm",
            "audit",
            "LOCKDOWN",
            "kaslr=1",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg_removal(arg, "remove"),
                    Err(ExecutorError::InvalidParam("remove"))
                ),
                "removing the bare key {arg} removes its protective value and must be refused"
            );
        }
        // The full weakening token stays removable, and so does an ordinary key.
        for arg in ["mitigations=off", "selinux=0", "audit=0", "quiet", "rhgb"] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_ok(),
                "{arg} must stay removable"
            );
        }
    }

    /// `lsm=` picks the LSM stack as `security=` does, and `audit=1` is what
    /// turns kernel auditing on, so dropping either weakens the next boot.
    #[test]
    fn kernel_arg_removal_refuses_the_lsm_and_audit_selectors() {
        for arg in ["lsm=landlock,lockdown,yama,apparmor", "audit=1", "Audit=1"] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_err(),
                "removing {arg} weakens the boot and must be refused"
            );
        }
    }

    /// `systemd.wants=` pulls a unit into the boot transaction as surely as
    /// `systemd.unit=` makes it the target: `systemd.wants=debug-shell.service`
    /// is the same root shell on tty9.
    #[test]
    fn kernel_arg_blocks_root_shell_units_pulled_in_by_wants() {
        for arg in [
            "systemd.wants=debug-shell.service",
            "systemd.wants=emergency.service",
            "rd.systemd.wants=rescue.target",
            "rd.systemd.wants=debug-shell.service",
            "SYSTEMD.WANTS=Debug-Shell.service",
        ] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_err(),
                "{arg} boots into a root shell and must be refused"
            );
        }
        // The allowlist names no `systemd.wants=`, whatever the unit.
        assert!(validated_safe_kernel_arg("systemd.wants=sshd.service", "add").is_err());
    }

    /// Weakenings the add screen missed: twins of arguments it already refused
    /// (`lsm=` for `security=`, `modprobe.blacklist=` for `module_blacklist=`), the
    /// initramfs shell, masking a unit at boot, and the per-mitigation switches.
    #[test]
    fn kernel_arg_blocks_the_remaining_weakenings() {
        for arg in [
            "lsm=landlock",
            "rd.shell",
            "rd.shell=1",
            "systemd.mask=auditd.service",
            "rd.systemd.mask=systemd-journald.service",
            "modprobe.blacklist=apparmor",
            "audit=0",
            "nopti",
            "nospectre_v1",
            "nospectre_v2",
            "spectre_v2=off",
            "spec_store_bypass_disable=off",
            "nokaslr",
            "NOPTI",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg(arg, "add"),
                    Err(ExecutorError::InvalidParam("add"))
                ),
                "{arg} weakens the next boot and must be refused"
            );
        }
        for arg in ["spectre_v2=on", "audit=1"] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_err(),
                "{arg} is not on the allowlist"
            );
        }
        assert!(validated_safe_kernel_arg("quiet", "add").is_ok());
    }

    /// The screen must not turn into "no removals at all" — an argument that is
    /// itself a weakening (the add-path refuses it) has to stay removable, or
    /// SysKnife could never undo `mitigations=off` on a host that already has it.
    #[test]
    fn kernel_arg_removal_allows_undoing_a_weakening_arg() {
        for arg in [
            "mitigations=off",
            "selinux=0",
            "enforcing=0",
            "apparmor=0",
            "pti=off",
            "lockdown=none",
            "debugfs=on",
            "init=/bin/sh",
            "single",
        ] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_ok(),
                "{arg} weakens the host, so removing it must stay allowed"
            );
        }
    }

    #[test]
    fn kernel_arg_removal_allows_ordinary_args() {
        for arg in [
            "quiet",
            "splash",
            "nomodeset",
            "console=ttyS0,115200",
            "rd.driver.blacklist=nouveau",
        ] {
            assert!(
                validated_safe_kernel_arg_removal(arg, "remove").is_ok(),
                "{arg} carries no boot-security meaning and must stay removable"
            );
        }
    }

    // A kernel argument is one token of the boot line. The denylists above read
    // the start of the value, so a value that carries a second token behind a
    // space, a tab or a newline would reach the boot line with that token
    // unscreened. NUL and other control bytes have no place in a boot argument.
    const NOT_ONE_KERNEL_TOKEN: &[&str] = &[
        "quiet init=/bin/sh",
        "x selinux=0",
        "quiet\tmitigations=off",
        "quiet\ninit=/bin/sh",
        "quiet\rsingle",
        "\u{0}nomodeset",
        "nomodeset\u{0}",
        "quiet\u{7f}",
        "quiet\u{a0}single",
        "console=\"ttyS0 init=/bin/sh\"",
        "quiet'",
        "quiet\\",
        "-b",
        "-quiet",
        "",
    ];

    #[test]
    fn set_kernel_arguments_refuses_a_value_that_is_not_one_token() {
        for arg in NOT_ONE_KERNEL_TOKEN {
            for key in ["add", "remove"] {
                assert!(
                    build_action_spec("SetKernelArguments", &json!({ key: [arg] })).is_err(),
                    "SetKernelArguments must refuse {key} {arg:?}"
                );
            }
        }
        let too_long = "a".repeat(crate::actions::validate::SAFE_ARG_MAX_BYTES + 1);
        for key in ["add", "remove"] {
            assert!(
                build_action_spec("SetKernelArguments", &json!({ key: [too_long] })).is_err(),
                "SetKernelArguments must refuse an over-long {key} value"
            );
        }
    }

    #[test]
    fn set_kernel_arguments_keeps_ordinary_tokens() {
        for arg in [
            "quiet",
            "nomodeset",
            "console=ttyS0,115200",
            "rd.driver.blacklist=nouveau",
            "video=HDMI-A-1:1920x1080@60",
            "nvidia-drm.modeset=1",
        ] {
            for key in ["add", "remove"] {
                assert!(
                    build_action_spec("SetKernelArguments", &json!({ key: [arg] })).is_ok(),
                    "SetKernelArguments must keep accepting {key} {arg:?}"
                );
            }
        }
        // `root=` picks the root filesystem the next boot mounts; it is not on
        // the allowlist, so neither list takes it.
        for key in ["add", "remove"] {
            assert!(
                build_action_spec(
                    "SetKernelArguments",
                    &json!({ key: ["root=UUID=0b1c-77aa"] })
                )
                .is_err(),
                "SetKernelArguments must refuse {key} root="
            );
        }
    }

    #[test]
    fn kernel_arg_blocks_systemd_unit_emergency_rescue() {
        assert!(matches!(
            validated_safe_kernel_arg("systemd.unit=emergency.target", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("systemd.unit=rescue.target", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("systemd.unit=single.target", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    /// Boot-mode and run tokens that systemd(1) and kernel-command-line(7)
    /// honour. `emergency`, `rescue`, `-b` and runlevels 2-5 pick the boot target
    /// as `single` and `1` do; `systemd.run=` runs a command as a root service
    /// after boot; `rdinit=` and `rd.systemd.unit=` are the initramfs twins of
    /// `init=` and `systemd.unit=`; `rd.break` and `break` stop in an initramfs
    /// root shell. tests/release/grub-kargs-edit.test.sh holds the helper to the
    /// same list.
    #[test]
    fn kernel_arg_blocks_boot_mode_and_run_tokens() {
        for arg in [
            "emergency",
            "rescue",
            "-b",
            "rd.emergency",
            "rd.rescue",
            "2",
            "3",
            "4",
            "5",
            "systemd.run=/tmp/x",
            "systemd.run_success_action=reboot",
            "systemd.run_failure_action=none",
            "rdinit=/bin/sh",
            "rd.break",
            "rd.break=pre-mount",
            "break",
            "break=premount",
            "rd.systemd.unit=emergency.target",
            "rd.systemd.unit=rescue.target",
            "rd.systemd.unit=debug-shell.service",
            "EMERGENCY",
            "Systemd.Run=/tmp/x",
        ] {
            assert!(
                matches!(
                    validated_safe_kernel_arg(arg, "add"),
                    Err(ExecutorError::InvalidParam("add"))
                ),
                "{arg} boots into a root shell or runs a root command and must be refused"
            );
        }
        // The allowlist names no systemd unit selector, whatever the unit.
        assert!(validated_safe_kernel_arg("rd.systemd.unit=graphical.target", "add").is_err());
        for arg in ["quiet", "splash", "loglevel=3"] {
            assert!(
                validated_safe_kernel_arg(arg, "add").is_ok(),
                "{arg} carries no boot-security meaning and must stay appendable"
            );
        }
    }

    #[test]
    fn kernel_arg_blocks_apparmor_disable() {
        assert!(matches!(
            validated_safe_kernel_arg("apparmor=0", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_mitigations_off() {
        assert!(matches!(
            validated_safe_kernel_arg("mitigations=off", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_lockdown_override() {
        assert!(matches!(
            validated_safe_kernel_arg("lockdown=none", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_pti_off() {
        assert!(matches!(
            validated_safe_kernel_arg("pti=off", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_smap_smep_disable() {
        assert!(matches!(
            validated_safe_kernel_arg("nosmap", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("nosmep", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn kernel_arg_blocks_single_user_shortcuts() {
        // Runlevel shortcuts that drop to a root shell.
        assert!(matches!(
            validated_safe_kernel_arg("single", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("s", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
        assert!(matches!(
            validated_safe_kernel_arg("1", "add"),
            Err(ExecutorError::InvalidParam("add"))
        ));
    }

    #[test]
    fn signal_process_guardrails() {
        // Reject pid 0 (whole process group) and 1 (init/systemd).
        for bad_pid in [0, 1] {
            let err = build_action_spec("SignalProcess", &json!({ "pid": bad_pid })).unwrap_err();
            assert!(
                matches!(err, ExecutorError::InvalidParam("pid")),
                "pid {bad_pid} must be rejected, got {err:?}"
            );
        }
        // Reject a signal outside the allowlist.
        let err = build_action_spec("SignalProcess", &json!({ "pid": 4242, "signal": "STOP" }))
            .unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("signal")),
            "got {err:?}"
        );
        // Missing pid is a MissingParam.
        assert!(matches!(
            build_action_spec("SignalProcess", &json!({})).unwrap_err(),
            ExecutorError::MissingParam("pid")
        ));
        // A valid pid + signal builds, and accepts a numeric string + SIG prefix.
        let spec = build_action_spec(
            "SignalProcess",
            &json!({ "pid": "4242", "signal": "sigkill" }),
        )
        .unwrap();
        assert_eq!(spec.action_name, "SignalProcess");
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/action-steps".to_string(),
                    "signal".to_string(),
                    "KILL".to_string(),
                    "4242".to_string()
                ],
            }
        );
        // Default signal is TERM when omitted.
        let spec = build_action_spec("SignalProcess", &json!({ "pid": 4242 })).unwrap();
        if let ActionMechanism::Command { args, .. } = spec.mechanism {
            assert_eq!(
                args,
                vec!["/usr/lib/sysknife/action-steps", "signal", "TERM", "4242"]
            );
        } else {
            panic!("expected Command mechanism");
        }
    }

    #[test]
    fn create_scheduled_job_validates_name_command_schedule() {
        // A newline in the command would inject extra unit directives.
        assert!(matches!(
            build_action_spec(
                "CreateScheduledJob",
                &json!({ "name": "backup", "command": "/bin/true\nExecStartPre=/evil", "schedule": "daily" })
            )
            .unwrap_err(),
            ExecutorError::InvalidParam("command")
        ));
        // A path-like / dotted name is rejected (must be a safe unit stem).
        assert!(matches!(
            build_action_spec(
                "CreateScheduledJob",
                &json!({ "name": "../evil", "command": "/bin/true", "schedule": "daily" })
            )
            .unwrap_err(),
            ExecutorError::InvalidParam("name")
        ));
        // A schedule with shell metacharacters is rejected by the charset gate.
        assert!(matches!(
            build_action_spec(
                "CreateScheduledJob",
                &json!({ "name": "backup", "command": "/bin/true", "schedule": "daily; rm -rf /" })
            )
            .unwrap_err(),
            ExecutorError::InvalidParam("schedule")
        ));
        // A valid job routes through the scoped helper with the right argv.
        let spec = build_action_spec(
            "CreateScheduledJob",
            &json!({ "name": "nightly-backup", "command": "/usr/bin/backup --full", "schedule": "*-*-* 02:00:00" }),
        )
        .unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/scheduled-job-edit".to_string(),
                    "--name".to_string(),
                    "nightly-backup".to_string(),
                    "--command".to_string(),
                    "/usr/bin/backup --full".to_string(),
                    "--schedule".to_string(),
                    "*-*-* 02:00:00".to_string(),
                ],
            }
        );
    }

    #[test]
    fn set_sshd_option_allowlist_guardrails() {
        // Non-allowlisted option rejected.
        assert!(matches!(
            build_action_spec(
                "SetSshdOption",
                &json!({ "option": "Ciphers", "value": "aes256-gcm@openssh.com" })
            )
            .unwrap_err(),
            ExecutorError::InvalidParam("option")
        ));
        // Allowlisted option, disallowed value.
        assert!(matches!(
            build_action_spec(
                "SetSshdOption",
                &json!({ "option": "PermitRootLogin", "value": "maybe" })
            )
            .unwrap_err(),
            ExecutorError::InvalidParam("value")
        ));
        // Valid combo routes through the scoped helper.
        let spec = build_action_spec(
            "SetSshdOption",
            &json!({ "option": "PasswordAuthentication", "value": "no" }),
        )
        .unwrap();
        assert_eq!(
            spec.mechanism,
            ActionMechanism::Command {
                program: "sudo",
                args: vec![
                    "/usr/lib/sysknife/sshd-option-edit".to_string(),
                    "--option".to_string(),
                    "PasswordAuthentication".to_string(),
                    "--value".to_string(),
                    "no".to_string(),
                ],
            }
        );
    }

    #[test]
    fn configure_unattended_upgrades_toggles_helper_flag() {
        for (enabled, flag) in [(true, "--enable"), (false, "--disable")] {
            let spec = build_action_spec(
                "ConfigureUnattendedUpgrades",
                &json!({ "enabled": enabled }),
            )
            .unwrap();
            assert_eq!(
                spec.mechanism,
                ActionMechanism::Command {
                    program: "sudo",
                    args: vec![
                        "/usr/lib/sysknife/unattended-upgrades-edit".to_string(),
                        flag.to_string(),
                    ],
                }
            );
        }
        assert!(matches!(
            build_action_spec("ConfigureUnattendedUpgrades", &json!({})).unwrap_err(),
            ExecutorError::MissingParam("enabled")
        ));
    }

    #[test]
    fn grub_set_kargs_append_blocks_single_user_shortcut() {
        // Regression: GrubSetKargs previously used only the charset validator,
        // which accepts the bare `single`/`s`/`1` runlevel shortcuts. The
        // kernel-arg allowlist must apply to `append` too — booting into a
        // single-user root shell is exactly the SetKernelArguments threat.
        // These tokens are valueless, so they pass the charset check and the
        // allowlist is the only thing stopping them — the call is load-bearing
        // here, not redundant with `validated_safe_arg`.
        for dangerous in ["single", "s", "1", "nosmap", "nosmep"] {
            let err = build_action_spec(
                "GrubSetKargs",
                &json!({ "append": [dangerous], "delete": [] }),
            )
            .unwrap_err();
            assert!(
                matches!(err, ExecutorError::InvalidParam("append")),
                "GrubSetKargs must reject append=[{dangerous:?}] via the allowlist, got {err:?}"
            );
        }
        // A benign flag still builds successfully.
        assert!(build_action_spec(
            "GrubSetKargs",
            &json!({ "append": ["quiet"], "delete": [] })
        )
        .is_ok());
    }

    #[test]
    fn kernel_arg_build_spec_rejects_dangerous_arg() {
        // End-to-end: build_action_spec must propagate the allowlist error.
        // This action does NOT apply the `validated_safe_arg` charset check,
        // so `init=/bin/bash` reaches `validated_safe_kernel_arg`, whose
        // `key=value` half is live here even though GrubSetKargs never reaches it.
        let err = build_action_spec(
            "SetKernelArguments",
            &json!({ "add": ["init=/bin/bash"], "remove": [] }),
        )
        .unwrap_err();
        assert!(
            matches!(err, ExecutorError::InvalidParam("add")),
            "expected InvalidParam(add), got {err:?}"
        );
    }

    #[test]
    fn grub_set_kargs_cannot_delete_a_protective_karg() {
        // A review flagged `delete: ["apparmor=1"]` as a way to strip AppArmor
        // because the kernel-arg denylist is not applied to `delete`. It is
        // not reachable: `delete` goes through `validated_safe_arg`, whose
        // charset excludes `=`, so any `key=value` token is refused before the
        // denylist would matter. Pinned here so a future widening of that
        // charset cannot silently open the hole.
        for karg in [
            "apparmor=1",
            "lockdown=confidentiality",
            "mitigations=auto",
            "pti=on",
            "selinux=1",
        ] {
            let err = build_action_spec("GrubSetKargs", &json!({ "append": [], "delete": [karg] }))
                .unwrap_err();
            assert!(
                matches!(err, ExecutorError::InvalidParam("delete")),
                "deleting {karg:?} must be refused, got {err:?}"
            );
        }
    }

    /// Every action that claims `rollback_available: true` MUST have a
    /// corresponding entry in `rollback_spec_for()`; every action that claims
    /// `false` MUST NOT. This prevents the spec and the executor from
    /// drifting apart.
    #[test]
    fn rollback_available_matches_rollback_spec_for_all_actions() {
        // Iterate the FULL catalogue (`crate::actions::all_specs`), not a
        // hand-picked subset of families — a manually-chained list here once
        // silently omitted `ppa`, `netplan`, `grub`, and `ubuntu_pro`, which is
        // exactly how `AddPpa`/`RemovePpa`/`NetplanSet`/`GrubSetKargs`/
        // `ProAttach`/`ProDetach` were able to claim `rollback_available: true`
        // with no matching `rollback_spec_for` entry for years without this
        // test catching it.
        for spec in crate::actions::all_specs() {
            let has_rollback = rollback_spec_for(spec.action_name).is_some();
            assert_eq!(
                spec.rollback_available,
                has_rollback,
                "action {:?}: rollback_available={} but rollback_spec_for returns {}",
                spec.action_name,
                spec.rollback_available,
                if has_rollback { "Some" } else { "None" },
            );
        }
    }

    // `home` reaches `useradd --create-home --home-dir <home>` as root, so it is
    // a path the caller chooses and root acts on. It was validated by
    // `validated_safe_arg`, which enforces a charset and rejects a leading dash
    // and accepts both `..` and a relative path. `validated_absolute_path`, in
    // the same file, rejects both, and every other root-acting path parameter
    // already uses it. The weaker of two adjacent validators was guarding the
    // more dangerous parameter.
    #[test]
    fn create_user_home_must_be_an_absolute_path_without_dot_dot() {
        for home in [
            "../../etc/skel",
            "/home/../etc",
            "home/alice",
            "/home/alice/../../../root",
        ] {
            let got =
                build_action_spec("CreateUser", &json!({ "username": "alice", "home": home }));
            assert!(
                got.is_err(),
                "CreateUser accepted home={home:?}, which useradd --home-dir runs as root"
            );
        }
        // An ordinary home directory must still work, or the guard has eaten
        // the feature rather than secured it.
        build_action_spec(
            "CreateUser",
            &json!({ "username": "alice", "home": "/home/alice" }),
        )
        .expect("a plain absolute home must still be accepted");
    }

    // ── Risk level reclassification (NIST 800-53 / CIS Controls v8.1) ────────
    // These five actions were incorrectly classified Medium; they must be High.
    // T1136.001 (CreateUser), T1562.004 (ConfigureFirewall), T1562.001 (MaskService),
    // supply-chain vector (AddPackageRepository), T1557 path (SetDnsServers).

    #[test]
    fn create_user_is_high_risk() {
        let spec = build_action_spec("CreateUser", &json!({ "username": "alice" })).unwrap();
        assert_eq!(
            spec.risk_level,
            RiskLevel::High,
            "CreateUser must be High (T1136.001 Persistence)"
        );
    }

    #[test]
    fn configure_firewall_is_high_risk() {
        let spec = build_action_spec(
            "ConfigureFirewall",
            &json!({ "zone": "public", "service": "ssh", "enabled": true }),
        )
        .unwrap();
        assert_eq!(
            spec.risk_level,
            RiskLevel::High,
            "ConfigureFirewall must be High (T1562.004 Defense Evasion)"
        );
    }

    #[test]
    fn mask_service_is_high_risk() {
        let spec = build_action_spec("MaskService", &json!({ "unit": "auditd.service" })).unwrap();
        assert_eq!(
            spec.risk_level,
            RiskLevel::High,
            "MaskService must be High (T1562.001 Impair Defenses)"
        );
    }

    #[test]
    fn add_package_repository_is_high_risk() {
        let spec = build_action_spec(
            "AddPackageRepository",
            &json!({ "repo_id": "my-repo", "repo_url": "https://ok.example/repo" }),
        )
        .unwrap();
        assert_eq!(
            spec.risk_level,
            RiskLevel::High,
            "AddPackageRepository must be High (supply-chain vector)"
        );
    }

    #[test]
    fn set_dns_servers_is_high_risk() {
        let spec = build_action_spec(
            "SetDnsServers",
            &json!({ "interface": "eth0", "servers": ["8.8.8.8"] }),
        )
        .unwrap();
        assert_eq!(
            spec.risk_level,
            RiskLevel::High,
            "SetDnsServers must be High (DNS hijacking / T1557)"
        );
    }
}