choir_cli/

acl.rs

//! Regenerating the readable half of an ACL file (D46).
//!
//! Grants are written against handles, because a channel is what
//! `signing_hash` covers and therefore what the log keeps forever. That
//! leaves the operator auditing lines like `7f3ac2ab19cd choir/choir.git
//! own`, which is unreadable, and unreadable authorization is
//! unaudited authorization.
//!
//! The settled answer is a generated trailing comment naming the person,
//! and the reason it is safe is one asymmetry: **the node's ACL parser
//! ignores everything after `#`.** A comment that has gone stale can
//! mislead a reader; it can never change a grant. The two rejected
//! options both failed on that axis — resolving names at load time turns
//! a deleted account into a config error someone has to notice, and a
//! separate roster file means auditing one grant needs two files open,
//! which in practice means the audit stops happening.
//!
//! This module is the pure half: text and a roster in, text out, no
//! network and no filesystem. The command that fetches the roster and
//! writes the file lives in `main.rs`, so everything with a decision in
//! it can be tested without either.
//!
//! # Examples
//!
//! ```
//! let mut roster = std::collections::BTreeMap::new();
//! roster.insert("7f3ac2ab19cd".to_string(), "Ada Lovelace".to_string());
//!
//! let rendered = choir_cli::acl::render("7f3ac2ab19cd choir/choir.git own\n", &roster);
//! assert!(rendered.contains("# Ada Lovelace"));
//! assert!(rendered.contains("7f3ac2ab19cd choir/choir.git own"));
//! ```

use std::collections::BTreeMap;

/// Handle to readable name, as `GET /api/accounts` reports it.
pub type Roster = BTreeMap<String, String>;

/// The line written above a rendered file, telling the next reader that
/// the comments are output rather than input.
pub const HEADER: &str = "# regenerated by `choir acl render` -- do not hand-edit comments";

/// Rewrites every grant line's trailing comment from `roster`.
///
/// The grant half of each line — everything before the first `#` — is
/// copied through byte for byte. That is the property this command
/// stands on: it edits an authorization file, and the one thing it must
/// never do is change what the file authorizes.
///
/// A subject the roster cannot name loses its comment rather than
/// keeping the one it had. That is not tidiness: the roster forgets a
/// name when the account is revoked, so a comment left behind would be
/// the deleted name surviving in a file, which is the whole thing the
/// deletion was for.
///
/// Standalone comment lines and blank lines are passed through
/// untouched. They are the operator's own writing, and a command that
/// regenerates comments is not a command that owns every comment.
#[must_use]
pub fn render(acl_text: &str, roster: &Roster) -> String {
    let mut out = String::with_capacity(acl_text.len() + 64);
    let ends_with_newline = acl_text.is_empty() || acl_text.ends_with('\n');
    let mut wrote_header = false;

    for line in acl_text.lines() {
        // The header is rewritten rather than duplicated: running the
        // command twice must produce the same file as running it once.
        if line.trim() == HEADER {
            continue;
        }
        if !wrote_header {
            out.push_str(HEADER);
            out.push('\n');
            wrote_header = true;
        }

        let grant = line.split('#').next().unwrap_or(line);
        // A line with no grant text is a comment or blank: the
        // operator's, not ours.
        if grant.trim().is_empty() {
            out.push_str(line);
            out.push('\n');
            continue;
        }

        let grant = grant.trim_end();
        out.push_str(grant);
        if let Some(name) = grant.split_whitespace().next().and_then(|s| roster.get(s)) {
            out.push_str("  # ");
            // A name carrying a newline would forge a grant line out of
            // a comment. The node refuses one at issue, so this is the
            // second of two defences rather than the only one.
            out.push_str(&name.replace(['\n', '\r'], " "));
        }
        out.push('\n');
    }

    if !wrote_header {
        out.push_str(HEADER);
        out.push('\n');
    }
    if !ends_with_newline {
        out.pop();
    }
    out
}

/// How many grant lines were rendered, and how many of them a name could
/// be found for.
///
/// Returned for the command's summary line, which is the only signal an
/// operator gets that a handle they expected to see named is not: a file
/// that renders no comments at all looks exactly like a file that has
/// no accounts.
#[must_use]
pub fn counts(acl_text: &str, roster: &Roster) -> (usize, usize) {
    let mut grants = 0;
    let mut named = 0;
    for line in acl_text.lines() {
        let grant = line.split('#').next().unwrap_or(line);
        if grant.trim().is_empty() {
            continue;
        }
        grants += 1;
        if grant
            .split_whitespace()
            .next()
            .is_some_and(|subject| roster.contains_key(subject))
        {
            named += 1;
        }
    }
    (grants, named)
}

#[cfg(test)]
mod tests {
    use super::{counts, render, Roster, HEADER};

    fn roster() -> Roster {
        let mut roster = Roster::new();
        roster.insert("7f3ac2ab19cd".to_string(), "Ada Lovelace".to_string());
        roster.insert("91bd04ff2a17".to_string(), "Grace Hopper".to_string());
        roster
    }

    /// The property the whole command rests on, asserted on the text
    /// rather than inferred from the code: what a line authorizes is
    /// byte-identical before and after.
    #[test]
    fn the_grant_half_of_every_line_survives_unchanged() {
        let before = "\
7f3ac2ab19cd choir/choir.git own
91bd04ff2a17 choir/choir.git write
0000deadbeef @node auditor
";
        let after = render(before, &roster());
        let grants: Vec<&str> = after
            .lines()
            .filter(|l| !l.trim().is_empty() && !l.trim_start().starts_with('#'))
            .map(|l| l.split('#').next().unwrap_or(l).trim_end())
            .collect();
        assert_eq!(
            grants,
            vec![
                "7f3ac2ab19cd choir/choir.git own",
                "91bd04ff2a17 choir/choir.git write",
                "0000deadbeef @node auditor",
            ],
            "rendering comments changed what the file authorizes: {after}"
        );
    }

    /// A handle the roster cannot name loses its comment, because the
    /// roster forgets a name exactly when the account is revoked. A
    /// comment left behind is the deleted name surviving in a file.
    #[test]
    fn a_forgotten_name_is_removed_rather_than_kept() {
        let stale = "7f3ac2ab19cd choir/choir.git own  # Ada Lovelace\n";
        let after = render(stale, &Roster::new());
        assert!(
            !after.contains("Ada Lovelace"),
            "a deleted name survived in the ACL file: {after}"
        );
        assert!(
            after.contains("7f3ac2ab19cd choir/choir.git own"),
            "the grant went with the name: {after}"
        );
    }

    /// Running it twice must produce what running it once produced, or
    /// the repair is not one an operator can run without thinking.
    #[test]
    fn rendering_is_idempotent() {
        let before = "7f3ac2ab19cd choir/choir.git own\n\n# my own note\n";
        let once = render(before, &roster());
        let twice = render(&once, &roster());
        assert_eq!(once, twice, "a second run changed the file");
        assert_eq!(once.matches(HEADER).count(), 1, "the header was duplicated");
    }

    /// The operator's own comment lines are theirs. A command that
    /// regenerates comments does not own every comment in the file.
    #[test]
    fn standalone_comments_and_blank_lines_are_left_alone() {
        let before = "# who can push to the demo repo\n\n7f3ac2ab19cd agents/demo write\n";
        let after = render(before, &roster());
        assert!(after.contains("# who can push to the demo repo"), "{after}");
        assert!(
            after.contains("\n\n"),
            "the blank line was swallowed: {after}"
        );
    }

    /// A stale comment can mislead a reader; it must never be able to
    /// become a grant. A name carrying a newline would do exactly that,
    /// so it is flattened here as well as refused at issue.
    #[test]
    fn a_name_cannot_smuggle_a_second_line_into_the_file() {
        let mut roster = Roster::new();
        roster.insert(
            "7f3ac2ab19cd".to_string(),
            "Ada\n0000deadbeef @node auditor".to_string(),
        );
        let after = render("7f3ac2ab19cd agents/demo read\n", &roster);
        assert!(
            !after.contains("\n0000deadbeef"),
            "a display name forged a grant line: {after}"
        );
    }

    /// The summary is what tells an operator that a handle they expected
    /// to see named is not: an unnamed file and an empty file look the
    /// same otherwise.
    #[test]
    fn the_summary_counts_grants_and_the_names_found_for_them() {
        let text = "\
# a note
7f3ac2ab19cd choir/choir.git own
0000deadbeef @node auditor

91bd04ff2a17 agents/demo write
";
        assert_eq!(counts(text, &roster()), (3, 2));
    }
}