workload_spec/

control_plane_install.rs

//! Shared install-script builder for a control-plane (yubaba + kamaji) roll.
//!
//! This is the ONE net-new mechanism of the rolling-upgrade envelope (R608):
//! the atomic fetch→verify→anchor→install→assert→restart of the signed
//! yubaba+kamaji pair. It lives here — in the crate BOTH the CLI orchestrator
//! and yubaba itself depend on — so the two apply transports share a single,
//! trusted script and cannot drift:
//!
//! - **SSH transport** (R608-F5, `app/yah/cli/src/rollout/apply.rs::apply_over_ssh`)
//!   pipes the script to `ssh <node> bash -s` from the orchestrator.
//! - **Mesh transport** (R608-F10, yubaba `POST /self-update`) runs the *same*
//!   script locally on the node via a `systemd-run` transient unit — no SSH.
//!
//! **The script body is not written here.** It lives beside this file as
//! [`control_plane_install.sh`](./control_plane_install.sh) and is `include_str!`d,
//! because a third caller — `scripts/roll-node.sh`, the one-node operator SSH
//! job (R755-F3) — has to run the identical bytes from bash with no Rust in the
//! loop. This function only prepends the four-variable prologue the template
//! declares (`URL` / `SHA` / `VER` / `SUDO`); `roll-node.sh` prepends the same
//! four. Keeping the body in a `format!` string would have forced that script to
//! become a fourth transcription of the most safety-critical code in the fleet
//! (`stand-up-yubaba.sh`'s install tail is already the second).
//!
//! The script is a state-preserving, atomic transcription of the install tail of
//! `stand-up-yubaba.sh`: fetch the signed release tarball, `sha256 -c` it against
//! the digest the signed manifest already resolved (callers only ever pass
//! manifest-derived values — there is no path for an AI or a wire request to
//! fabricate a version/url/digest), extract, leave a dated rollback anchor beside
//! every file it is about to replace, stage each file next to its target on the
//! same filesystem, then `mv` it into place so a half-written
//! `/usr/local/bin/yubaba` can never appear. yubaba + kamaji install as one
//! atomic pair (W275 OQ5).
//!
//! **Success is proved by content, never by `--version`.** After the rename the
//! script hashes each installed binary against the file it extracted from the
//! manifest-verified tarball. The version string is the workspace version baked
//! in at build time and can be right on a binary that predates the code it
//! claims — us-east-001 reported kamaji 0.8.22 while carrying none of the 0.8.22
//! tree (R746-T3). The hash chain manifest → tarball → extracted → installed has
//! no version string in it.
//!
//! **Never touches durable state.** The script contains no reference to
//! `/var/lib/yah-cloud/identity.json` (the ed25519 host identity — wiping it
//! forces a re-TOFU and breaks hostkey-drift detection, the R589 gotcha) or the
//! raft log dir. A roll moves `/usr/local/bin` bytes + unit files, nothing else.
//! The [`tests::script_never_touches_durable_state`] test is the guard.

/// Single-quote a value for safe embedding inside the generated bash. Callers
/// only ever embed manifest-derived URLs/digests (already constrained) and a
/// version string, but we quote defensively regardless.
fn sh_squote(s: &str) -> String {
    format!("'{}'", s.replace('\'', r"'\''"))
}

/// The canonical roll script body, shared verbatim with `scripts/roll-node.sh`.
/// Expects the four-variable prologue [`build_install_script`] emits.
pub const INSTALL_SCRIPT_TEMPLATE: &str = include_str!("control_plane_install.sh");

/// Build the self-contained install script for the yubaba+kamaji pair.
///
/// `sudo` is `true` when the executing user is not root (e.g. an SSH login as
/// `debian@…`), matching `stand-up-yubaba.sh`'s `SUDO` convention. The mesh
/// (self-update) path runs the script as root inside a `systemd-run` transient
/// unit, so it passes `sudo = false`. The script is idempotent and atomic; it
/// anchors what it is about to replace, restarts kamaji then yubaba (W154
/// supervision order) and echoes the installed versions so the caller can log
/// them — after having already proved the install by hash, not by those strings.
///
/// `version`/`url`/`sha256` MUST come from a signed release manifest — this
/// builder does no verification of its own beyond emitting the `sha256sum -c`
/// check; integrity rests on the caller only ever passing manifest-resolved
/// values.
pub fn build_install_script(version: &str, url: &str, sha256: &str, sudo: bool) -> String {
    let sudo_kw = if sudo { "sudo" } else { "" };
    format!(
        "SUDO={sudo_kw}\nURL={url}\nSHA={sha}\nVER={ver}\n{body}",
        sudo_kw = sudo_kw,
        url = sh_squote(url),
        sha = sh_squote(sha256),
        ver = sh_squote(version),
        body = INSTALL_SCRIPT_TEMPLATE,
    )
}

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

    #[test]
    fn script_embeds_the_signed_digest_and_url() {
        let url = "https://cdn.yah.dev/yubaba/0.8.19/yubaba-0.8.19-x86_64-unknown-linux-musl.tar.gz";
        let sha = "abc123def456";
        let s = build_install_script("0.8.19", url, sha, false);
        assert!(s.contains(sha), "script must carry the manifest sha256");
        assert!(s.contains(url), "script must carry the manifest url");
        assert!(s.contains("sha256sum -c -"), "script must verify the digest");
    }

    #[test]
    fn script_is_atomic_and_installs_the_whole_pair() {
        let s = build_install_script("0.8.19", "u", "d", false);
        // Atomic: stage-then-rename, never a direct write to the live path.
        assert!(s.contains("mv -f"), "install must be an atomic rename");
        assert!(s.contains(".roll-new.$$"), "install must stage to a temp name");
        // Every binary + all four unit files (scryer and the passway pair
        // conditionally — see the dedicated tests below).
        for target in [
            "/usr/local/bin/yubaba",
            "/usr/local/bin/kamaji",
            "/usr/local/bin/yah-scryer",
            "/usr/local/bin/passway",
            "/usr/local/bin/passway-demux",
            "/etc/systemd/system/yubaba.slice",
            "/etc/systemd/system/kamaji.service",
            "/etc/systemd/system/yubaba.service",
            "/etc/systemd/system/yah-scryer.service",
        ] {
            assert!(s.contains(target), "script must install {target}");
        }
        // Restart order: kamaji before yubaba (W154).
        let k = s.find("restart kamaji.service").unwrap();
        let y = s.find("restart yubaba.service").unwrap();
        assert!(k < y, "kamaji must restart before yubaba");
        assert!(s.contains("daemon-reload"));
    }

    #[test]
    fn scryer_install_is_conditional_on_the_tarball_carrying_it() {
        // R556-F6 gate (b): yah-scryer joined the tarball at 0.8.32. A
        // rollback to a pre-scryer release must still succeed — the script
        // must gate every scryer action on the member existing rather than
        // failing on it, and must leave an already-installed scryer alone.
        let s = build_install_script("0.8.32", "u", "d", true);
        assert!(
            s.contains(r#"if [ -e "$D/yah-scryer" ]; then"#),
            "scryer install must be gated on the tarball carrying the binary"
        );
        assert!(
            s.contains(r#"assert_installed_bytes "$D/yah-scryer" /usr/local/bin/yah-scryer"#),
            "installed scryer bytes must be content-asserted like the pair"
        );
        // First install has never been enabled; later rolls no-op.
        assert!(s.contains("enable yah-scryer.service"));
        // The scryer restart must come after the W154 pair restart — it is
        // located by yubaba, not driven by it (A049), and must not perturb
        // the kamaji→yubaba order.
        assert!(
            s.find("restart yubaba.service").unwrap()
                < s.find("restart yah-scryer.service").unwrap(),
            "scryer restarts after the supervision pair"
        );
    }

    #[test]
    fn passway_installs_conditionally_and_never_restarts_the_front_door() {
        // R870-B2: passway + passway-demux joined the tarball at 0.8.33, giving
        // the sovereign front door its first distribution path. Same
        // conditional shape as scryer, so a rollback to a pre-0.8.33 release
        // still succeeds.
        let s = build_install_script("0.8.33", "u", "d", true);
        assert!(
            s.contains(r#"if [ -e "$D/passway" ]; then"#),
            "passway install must be gated on the tarball carrying the binary"
        );
        for bin in ["passway", "passway-demux"] {
            assert!(
                s.contains(&format!(
                    r#"assert_installed_bytes "$D/{bin}"       /usr/local/bin/{bin}"#
                )) || s.contains(&format!(
                    r#"assert_installed_bytes "$D/{bin}" /usr/local/bin/{bin}"#
                )),
                "installed {bin} bytes must be content-asserted like the pair"
            );
        }
        // THE LOAD-BEARING NEGATIVE. passway cannot hot-swap a cert (tls.rs
        // "The reload gap"), so `systemctl restart` on a door drops in-flight
        // connections on public :443. A roll stages the bytes; the operator
        // chooses when to take the blip. If someone later adds a restart here,
        // every fleet roll starts cutting live traffic on yah.dev — and it
        // would look like an obvious omission being fixed.
        let exec = executable_lines(&s);
        for unit in [
            "passway.service",
            "passway-test.service",
            "passway-demux.service",
            "passway-http-router.service",
        ] {
            assert!(
                !exec.contains(unit),
                "a roll must not name {unit} — see R870-T3 for the graceful path"
            );
        }
    }

    #[test]
    fn the_http_router_rides_its_own_conditional_not_the_passway_pairs() {
        // R870-F1: the :80 tier joined at 0.8.34, one release AFTER the passway
        // pair. Gating it on HAS_PASSWAY would make this script fail against
        // every 0.8.33 tarball — which is exactly the rollback path the
        // conditional shape exists to keep working.
        let s = build_install_script("0.8.34", "u", "d", true);
        assert!(
            s.contains(r#"if [ -e "$D/passway-http-router" ]; then"#),
            "the :80 tier must be gated on its own tarball member"
        );
        assert!(
            s.contains(
                r#"assert_installed_bytes "$D/passway-http-router" /usr/local/bin/passway-http-router"#
            ),
            "installed http-router bytes must be content-asserted like the pair"
        );
        assert!(
            s.contains("anchor /usr/local/bin/passway-http-router"),
            "there must be a way back from a :80 roll"
        );
    }

    #[test]
    fn the_graceful_upgrade_helper_rides_the_roll_but_its_dropin_does_not() {
        // R870-T3. The helper is the ExecReload= that makes a cert rotation a
        // process swap: fleet-wide, no node state, so it installs like a binary
        // and gets the same rollback anchor and content assertion.
        let s = build_install_script("0.8.34", "u", "d", true);
        assert!(
            s.contains(r#"if [ -e "$D/passway-graceful-upgrade" ]; then"#),
            "the helper must be gated on its own tarball member, like the :80 tier"
        );
        assert!(
            s.contains(
                r#"assert_installed_bytes "$D/passway-graceful-upgrade" /usr/local/bin/passway-graceful-upgrade"#
            ),
            "installed helper bytes must be content-asserted"
        );
        assert!(
            s.contains("anchor /usr/local/bin/passway-graceful-upgrade"),
            "there must be a way back from a helper roll"
        );
        // The DROP-IN that arms it is node state: it lands in
        // /etc/systemd/system/<unit>.service.d/ and the unit name differs per
        // door. Naming it in an `echo` is how an operator learns the reload verb
        // exists; writing it would put a roll in the business of rewriting a
        // live door's unit configuration.
        for line in executable_lines(&s)
            .lines()
            .filter(|l| l.contains("passway-graceful-upgrade.conf"))
        {
            assert!(
                line.trim_start().starts_with("echo "),
                "the script may print the drop-in's name, never install it: {line}"
            );
        }
    }

    /// The script with every comment line removed — i.e. only the lines bash
    /// will actually execute. The template documents the durable-state rule in
    /// prose *by naming the paths it must not touch*, so the guard below has to
    /// look at commands, not at the whole file, or the doc comment describing
    /// the property would be what breaks the test asserting it.
    fn executable_lines(script: &str) -> String {
        script
            .lines()
            .filter(|l| !l.trim_start().starts_with('#'))
            .collect::<Vec<_>>()
            .join("\n")
    }

    #[test]
    fn script_never_touches_durable_state() {
        // The load-bearing safety property: a roll moves binaries + unit files
        // ONLY. Wiping identity.json forces a re-TOFU (R589 gotcha); touching
        // the raft dir corrupts consensus. The script must reference neither.
        let s = executable_lines(&build_install_script("0.8.19", "u", "d", true));
        assert!(!s.contains("identity.json"), "must not touch host identity");
        assert!(!s.contains("/var/lib/yah-cloud"), "must not touch state dir");
        assert!(!s.contains("raft"), "must not touch the raft log dir");
        assert!(!s.contains("rm -rf /"), "must not wipe system paths");
        // Scryer's events.db is durable per-node state the same way — a roll
        // replaces the binary + unit, never the store (R556-F6 gate (b)).
        assert!(
            !s.contains("/var/lib/yah/scryer"),
            "must not touch the scryer event store"
        );
    }

    #[test]
    fn script_anchors_every_file_it_replaces_before_replacing_it() {
        // R755-F3. Every path the script installs must first be copied to a
        // dated `.rollback-YYYYMMDD` sibling — the convention the fleet's boxes
        // already carry — and the anchoring must happen BEFORE the install, or
        // the anchor holds the new build and there is no way back.
        let s = build_install_script("0.8.19", "u", "d", true);
        let first_anchor = s.find("anchor /usr/local/bin/yubaba").expect("anchors");
        let first_install = s.find("install_atomic \"$D/yubaba\"").expect("installs");
        assert!(
            first_anchor < first_install,
            "anchors must be written before anything is replaced"
        );
        assert!(s.contains(r#"STAMP="$(date -u +%Y%m%d)""#));
        for target in [
            "/usr/local/bin/yubaba",
            "/usr/local/bin/kamaji",
            "/usr/local/bin/yah-scryer",
            "/usr/local/bin/passway",
            "/usr/local/bin/passway-demux",
            "/etc/systemd/system/yubaba.slice",
            "/etc/systemd/system/kamaji.service",
            "/etc/systemd/system/yubaba.service",
            "/etc/systemd/system/yah-scryer.service",
        ] {
            assert!(
                s.contains(&format!("anchor {target}\n")),
                "every installed path needs a rollback anchor, missing {target}"
            );
        }
    }

    #[test]
    fn anchoring_is_idempotent_within_a_day() {
        // The subtle half: a second roll on the same day must NOT re-anchor,
        // or the escape hatch gets overwritten with the build being escaped.
        let s = build_install_script("0.8.19", "u", "d", true);
        assert!(
            s.contains(r#"if [ ! -e "$1.rollback-$STAMP" ]; then"#),
            "anchor must refuse to overwrite an existing same-day anchor"
        );
    }

    #[test]
    fn success_is_asserted_by_content_not_by_version_string() {
        // R746-T3's trap: `--version` reports the workspace version baked in at
        // build time and was right on a binary carrying none of that version's
        // code. The proof has to be a hash of the installed bytes against the
        // bytes extracted from the manifest-verified tarball.
        let s = build_install_script("0.8.19", "u", "d", true);
        for pair in [
            r#"assert_installed_bytes "$D/yubaba" /usr/local/bin/yubaba"#,
            r#"assert_installed_bytes "$D/kamaji" /usr/local/bin/kamaji"#,
        ] {
            assert!(s.contains(pair), "missing content assertion: {pair}");
        }
        // …and a mismatch must fail the roll, not merely print.
        let body = &s[s.find("assert_installed_bytes() {").expect("assert fn")..];
        assert!(
            body.contains("content assertion FAILED") && body.contains("exit 1"),
            "a content mismatch must exit nonzero so the caller sees a failed roll"
        );
        // The assertion must land before the restart — restarting onto bytes
        // you haven't proved is the failure mode this closes.
        assert!(
            s.find("assert_installed_bytes \"$D/yubaba\"").unwrap()
                < s.find("systemctl restart kamaji.service").unwrap(),
            "content must be proved before the supervision tree restarts"
        );
    }

    #[test]
    fn the_template_is_the_only_copy_of_the_body() {
        // scripts/roll-node.sh runs these same bytes with no Rust in the loop,
        // so build_install_script must be a prologue over the template and
        // nothing more. If this drifts, the SSH job and the mesh self-update
        // stop being the same roll.
        let s = build_install_script("0.8.19", "u", "d", false);
        assert!(
            s.ends_with(INSTALL_SCRIPT_TEMPLATE),
            "the built script must be prologue + the shared template, verbatim"
        );
        let prologue = &s[..s.len() - INSTALL_SCRIPT_TEMPLATE.len()];
        assert_eq!(
            prologue.lines().count(),
            4,
            "the prologue is exactly URL/SHA/VER/SUDO — anything else belongs in the template"
        );
    }

    #[test]
    fn sudo_prefix_tracks_the_caller() {
        let s = build_install_script("0.8.19", "u", "d", true);
        assert!(s.contains("SUDO=sudo"));
        let s = build_install_script("0.8.19", "u", "d", false);
        assert!(s.contains("SUDO=\n") || s.contains("SUDO="));
    }
}