//! `continuum-party`: a party's client of a federation (`docs/federation.md`). It signs its //! party's events with one of its keys (`--key`: an OpenSSH private key file, or a public //! key the ssh-agent at `SSH_AUTH_SOCK` holds, given itself or in a file), puts them //! through a node's API (`--node`, its user and password in the URL, or `--token`), and //! keeps its party's record (`--record`, `client::Record`), by which it votes, written //! before a vote is sent. Its options may be set in configuration files as the node's are //! (`--config`, `config::PARTY_OPTIONS`): the same format, imports and all. //! //! * `init PARTY`: begins a record of `PARTY`, on the version current now; with `--root //! FILE`, from the file the store's swarm starts from, for a party that never voted in //! it: the record casts on every version, the first too; //! * `write PATH VALUE`: writes `VALUE` (JSON) at `PATH`; //! * `keys`, `nodes`: the party's key set (`authorized_keys` lines, each one argument, //! their comments left out) or node list (node IDs) as it counts at the node, one a line //! (`--list`); or written: with `--add` and `--remove`, the set or list as it counts, //! changed; with `--set`, set whole. One left empty is written with `--force` only; //! * `next`: the version after the current one, to change and propose: the current one //! numbered on, naming its hash, without its checkpoint (JSON), to standard output; //! * `propose FILE`: proposes the version `FILE` holds (JSON), where a party may back it //! (`client::backable`), and says the proposal's hash; with `--yes`, votes `true` on it //! too, as `vote` does; //! * `vote PROPOSAL yes|no`: votes on the proposal of hash `PROPOSAL` on the current //! version, by the record; with `--through`, through the node that votes for the //! party by itself and keeps its record, as such a party votes by hand; //! * `again`: signs again what a move refused; //! * `twice RECORD...`: names, from the records of parties' clients, a party that voted //! twice; //! * `proposals`: the proposals on the current version at the node, each with whether it //! passed or is dead, who voted what, and what its version changes (`client::changes`); //! * `root FILE`: the root of the federation whose first version `FILE` holds (JSON), //! the file its founders start its swarm from (`--store-root`), to standard output; //! * `fork FILE HEAD...`: the root of the fork at the heads named by the version `FILE` //! holds, as the node builds it, with the events it keeps: the file the fork's founders //! start its swarm from, to standard output; //! * `check FILE`: what the node finds of the fork whose root `FILE` holds: whether it //! builds it, what it holds that its heads lack, and the parties whose keys it gives //! otherwise. //! //! Votes, proposals, key sets and node lists are signed with a key the current version //! names for the party, which the client checks first (`Signer::named_by`): where its key //! isn't one, only a version naming the party's keys or list anew changes them. use std::collections::BTreeSet; use std::path::{Path, PathBuf}; use anyhow::{Context, Result, anyhow, bail}; use clap::{Arg, ArgAction, ArgGroup, ArgMatches, Command}; use ed25519_dalek::SigningKey; use serde::Deserialize; use serde_json::Value as JsonValue; use super::client::{self, Record}; use super::event::{self, Does, Event, Signed}; use super::fold::Federation; use super::jcs::Json; use super::judge; use super::keys::{self, Key}; use super::revision::{FEATURES, Revision}; use super::store::Id; use super::store::memory::Store; use super::version::Version; use crate::access::sshsig::PublicKey; use crate::config; /// The client's options (`config::PARTY_OPTIONS`), as the command line and configuration /// files set them. #[derive(Deserialize)] #[serde(rename_all = "kebab-case", deny_unknown_fields)] struct Options { #[serde(default = "default_node")] node: String, token: Option, key: Option, record: Option, } fn default_node() -> String { "http://localhost:3000".to_owned() } fn command() -> Command { let id = |name: &'static str| Arg::new(name).required(true); let command = Command::new("continuum-party") .version(env!("CARGO_PKG_VERSION")) .long_version(crate::release::described()) .about("A party's client of a federation: signs its events, and votes by its record"); config::with_options(command, config::PARTY_OPTIONS) .subcommand_required(true) .subcommand( Command::new("init") .about("Begins a record") .arg(id("party")) .arg( Arg::new("root") .long("root") .value_name("FILE") .help("From the file the store's swarm starts from, for a party that never voted in it"), ), ) .subcommand( Command::new("write") .about("Writes a value (JSON) at a path") .arg(id("path")) .arg(id("value")), ) .subcommand( Command::new("keys") .about( "The party's key set as it counts at the node, or written with keys added, \ taken off, or set whole", ) .args(changing("KEY", "keys", "key set")) .group(changes()), ) .subcommand( Command::new("nodes") .about( "The party's node list as it counts at the node, or written with nodes \ added, taken off, or set whole", ) .args(changing("NODE", "nodes", "node list")) .group(changes()), ) .subcommand( Command::new("next") .about( "The version after the current one, to change and propose: numbered on, \ naming the current one's hash, without its checkpoint", ) .arg( Arg::new("revision") .long("revision") .value_name("FEATURE") .help( "Following the revision that adds FEATURE (federation.md, Changing \ the federation): pass it once every party's nodes run a continuum \ that knows it", ), ), ) .subcommand( Command::new("propose") .about("Proposes the version a file holds (JSON), and says the proposal's hash") .arg(id("file")) .arg( Arg::new("yes") .long("yes") .action(ArgAction::SetTrue) .help("Votes true on it too, by the record, as vote does"), ), ) .subcommand( Command::new("vote") .about("Votes on a proposal on the current version, by its hash") .arg(id("proposal")) .arg(Arg::new("yes").required(true).value_parser(["yes", "no"])) .arg( Arg::new("through") .long("through") .action(ArgAction::SetTrue) .help("Through the node, which votes for the party and keeps its record"), ), ) .subcommand(Command::new("again").about("Signs again what a move refused")) .subcommand( Command::new("root") .about("The root of the federation whose first version a file holds (JSON)") .arg(id("file")), ) .subcommand( Command::new("fork") .about("The root of the fork at heads by the version a file holds, as the node builds it") .arg(id("file")) .arg(Arg::new("heads").num_args(1..).required(true)), ) .subcommand( Command::new("check") .about("What the node finds of the fork whose root a file holds") .arg(id("file")), ) .subcommand(Command::new("judge").about( "What a store makes of the histories its input spells, in a format every release \ keeps (federation-tests.md, Against released revisions)", )) .subcommand(Command::new("proposals").about( "The proposals on the current version: whether each passed or is dead, who voted \ what, and what it changes", )) .subcommand( Command::new("twice") .about("Names, from records, a party that voted twice") .arg( Arg::new("records") .num_args(1..) .required(true) .action(ArgAction::Append), ), ) } /// What lists or changes the party's key set or node list (`whole`), of `items` named /// `value`: `--list`, as it counts, what the command does given none of the others; /// `--add` and `--remove`, changing it as it counts; `--set`, setting it whole; `--force`, /// writing it empty. fn changing(value: &'static str, items: &str, whole: &str) -> [Arg; 5] { [ Arg::new("list") .long("list") .action(ArgAction::SetTrue) .conflicts_with("changes") .help(format!( "Shows the party's {whole} as it counts at the node, one a line: what the \ command does given nothing" )), Arg::new("add") .long("add") .value_name(value) .num_args(1..) .action(ArgAction::Append) .help(format!( "Adds these {items} to the party's {whole}, as it counts at the node" )), Arg::new("remove") .long("remove") .value_name(value) .num_args(1..) .action(ArgAction::Append) .help(format!( "Takes these {items} off the party's {whole}, as it counts at the node" )), Arg::new("set") .long("set") .value_name(value) .num_args(0..) .action(ArgAction::Append) .conflicts_with_all(["add", "remove"]) .help(format!("Sets the party's {whole} to these {items}, whole")), Arg::new("force") .long("force") .action(ArgAction::SetTrue) .requires("changes") .help(format!( "Writes the party's {whole} where the change leaves it empty" )), ] } /// What changes a key set or node list: `--add`, `--remove`, `--set`. fn changes() -> ArgGroup { ArgGroup::new("changes") .args(["add", "remove", "set"]) .multiple(true) } /// Runs the client, as its arguments say. pub(crate) async fn main() -> Result<()> { let matches = command().get_matches(); let (name, sub) = matches.subcommand().expect("a subcommand is required"); let (merged, _) = config::merged(&matches, config::PARTY_OPTIONS)?; let options: Options = config::read(&merged)?; if name == "twice" { let records = sub .get_many::("records") .into_iter() .flatten() .map(|path| Record::load(Path::new(path)).map_err(|why| anyhow!(why))) .collect::>>()?; for (version, party, why) in client::voted_twice(&records) { println!("{party} voted twice on version {version}: {why}"); } return Ok(()); } if name == "root" { let version = version_in(sub.get_one::("file").expect("required"))?; let version = Version::read(&version).map_err(|why| anyhow!("no version: {why}"))?; let root = event::Checkpoint { at: Vec::new(), keeps: Vec::new(), version, } .bytes(); if let Err(refused) = Store::::new(root.clone(), Vec::new()) { bail!("no federation's root: {}", refused.0); } return out(&super::fork::root_file(&root, &[])); } if name == "judge" { let mut input = String::new(); std::io::Read::read_to_string(&mut std::io::stdin(), &mut input)?; let histories = judge::read(&input).map_err(|why| anyhow!(why))?; print!("{}", judge::judge(&histories)); return Ok(()); } let node = Node::new(&options)?; if name == "proposals" { return proposals(&node).await; } if name == "next" { let current = node.current().await?; let feature = sub.get_one::("revision"); let next = next(¤t, feature.map(String::as_str))?; if feature.is_none() { // A later revision this client and the node know, said. let known = node.revisions().await?; if let Some(later) = Revision::known() .filter(|revision| *revision > current.revision && known.contains(&revision.id())) .last() { let name = later .features() .last() .expect("a later revision adds one") .name(); eprintln!( "The node knows {later}, the current version follows {}: --revision {name} \ moves to it, once every party's nodes run a continuum that knows it", current.revision ); warn_unready(&node.counts().await?, later); } } else if let Some(revision) = next["revision"] .as_str() .and_then(Id::from_hex) .and_then(|id| Revision::of(&id)) && revision != current.revision { warn_unready(&node.counts().await?, revision); } println!("{}", serde_json::to_string_pretty(&next)?); return Ok(()); } if name == "fork" { let version = version_in(sub.get_one::("file").expect("required"))?; let heads = strings(sub, "heads"); let body = serde_json::json!({ "heads": heads, "version": serde_json::from_slice::(&version.bytes())?, }); return out(&node.post_for_bytes("/admin/events/fork", &body).await?); } if name == "check" { let file = sub.get_one::("file").expect("required"); let bytes = std::fs::read(file).with_context(|| format!("Reading {file}"))?; let check = node.post_bytes("/events/fork", bytes).await?; let fork = check["fork"].as_str().unwrap_or_default(); match (check["builds"].as_bool(), check["why"].as_str()) { (Some(true), _) => println!("{fork}: built here, byte for byte"), (_, Some(why)) => println!("{fork}: not built here: {why}"), _ => println!("{fork}: not built here: another root at its heads"), } for id in check["lacking"].as_array().into_iter().flatten() { println!("its heads lack {}", id.as_str().unwrap_or_default()); } for (party, keys) in check["keys"].as_object().into_iter().flatten() { println!( "{party}'s keys: {} here, {} in the fork", keys["there"], keys["fork"] ); } return Ok(()); } // A party that has a node vote by itself votes by hand only through it. if name == "vote" && sub.get_flag("through") { let proposal = sub.get_one::("proposal").expect("required"); let yes = sub.get_one::("yes").map(String::as_str) == Some("yes"); let answer = node .post( "/admin/events/vote", &serde_json::json!({"proposal": proposal, "yes": yes}), ) .await?; println!("{} cast", answer["id"].as_str().unwrap_or_default()); return Ok(()); } let path = PathBuf::from( options .record .as_ref() .context("--record names the party's record")?, ); if name == "init" { if path.exists() { bail!("{} holds a record already", path.display()); } let party = sub.get_one::("party").expect("required"); let record = match sub.get_one::("root") { Some(file) => { let bytes = std::fs::read(file).with_context(|| format!("Reading {file}"))?; let (root, kept) = super::fork::read_root_file(&bytes); if let Err(refused) = Store::::new(root.clone(), kept) { bail!("no store's root: {}", refused.0); } Record::before(Id::of(&root), party) } None => { let (store, _) = node.summary().await?; Record::begin(store, party, &node.current().await?) } }; record.save(&path).map_err(|why| anyhow!(why))?; println!("began a record of {party}, of the store {}", record.store); return Ok(()); } let mut record = Record::load(&path).map_err(|why| anyhow!(why))?; // The party's key set or node list as it counts, given no change: no key needed. if matches!(name, "keys" | "nodes") && !sub.contains_id("changes") { for item in listed(&node.counts().await?, &record.party, name) { println!("{item}"); } return Ok(()); } let key = signing_key(&options)?; let signer = Signer { key, party: record.party.clone(), }; match (name, sub) { ("write", sub) => { let path_to = sub.get_one::("path").expect("required"); let value: JsonValue = serde_json::from_str(sub.get_one::("value").expect("required")) .context("the value isn't JSON")?; let value = client::json(&value).map_err(|why| anyhow!(why))?; sign( &node, &signer, &mut record, &path, event::write(path_to, value), ) .await } ("keys", sub) => { // As the federation spells a key: without the line's comment. let spelled = |name: &str| { strings(sub, name) .iter() .map(|line| { Key::parse(line) .map(|key| key.line()) .map_err(|why| anyhow!("{line:?}: {why}")) }) .collect::>>() }; let counts = node.counts().await?; signer.named_by(¤t(&counts)?)?; let party = &signer.party; let keys = changed( listed(&counts, party, "keys"), sub.contains_id("set").then(|| spelled("set")).transpose()?, spelled("add")?, spelled("remove")?, sub.get_flag("force"), &format!("{party}'s key set"), &format!("none of {party}'s writes would count"), )?; sign(&node, &signer, &mut record, &path, event::keys(&keys)).await } ("nodes", sub) => { let given = |name: &str| -> Result> { let nodes = strings(sub, name); match nodes.iter().find(|id| !keys::node_id(id)) { Some(none) => bail!("{none:?} isn't a node ID"), None => Ok(nodes), } }; let counts = node.counts().await?; signer.named_by(¤t(&counts)?)?; let party = &signer.party; let nodes = changed( listed(&counts, party, "nodes"), sub.contains_id("set").then(|| given("set")).transpose()?, given("add")?, given("remove")?, sub.get_flag("force"), &format!("{party}'s node list"), &format!("none of {party}'s nodes would be members"), )?; sign(&node, &signer, &mut record, &path, event::nodes(&nodes)).await } ("propose", sub) => { let version = version_in(sub.get_one::("file").expect("required"))?; let current = node.current().await?; signer.named_by(¤t)?; let proposed = client::backable(¤t, &version) .map_err(|why| anyhow!("not a version a party may back: {why}"))?; sign( &node, &signer, &mut record, &path, event::proposal(&version), ) .await?; println!("proposal {}", proposed.hash); if sub.get_flag("yes") { vote(&node, &signer, &mut record, &path, proposed.hash, true).await?; } Ok(()) } ("vote", sub) => { let proposal = Id::from_hex(sub.get_one::("proposal").expect("required")) .context("not a proposal's hash")?; let yes = sub.get_one::("yes").map(String::as_str) == Some("yes"); vote(&node, &signer, &mut record, &path, proposal, yes).await } ("again", _) => again(&node, &signer, &mut record, &path).await, _ => unreachable!("every subcommand handled"), } } /// The party's keys or nodes (`what`) as they count, as `counts` names them. fn listed(counts: &JsonValue, party: &str, what: &str) -> Vec { counts["parties"][party][what] .as_array() .into_iter() .flatten() .filter_map(|value| value.as_str().map(str::to_owned)) .collect() } /// The key set or node list to write: `set`, where given, else `now`, as it counts, with /// `add` added and `remove` taken off, each of which must change it. Left empty, only with /// `force`, as then `empty` (`what` names the set or list in the errors). Said before it /// is signed. fn changed( now: Vec, set: Option>, add: Vec, remove: Vec, force: bool, what: &str, empty: &str, ) -> Result> { let mut list = Vec::new(); for item in set.unwrap_or(now) { if list.contains(&item) { bail!("{what} would hold {item} twice"); } list.push(item); } for item in add { if list.contains(&item) { bail!("{what} holds {item} already"); } list.push(item); } for item in remove { let Some(at) = list.iter().position(|held| *held == item) else { bail!("{what} doesn't hold {item}"); }; list.remove(at); } if list.is_empty() && !force { bail!("{what} would be empty: {empty}. --force writes it so"); } let shown = if list.is_empty() { "none".to_owned() } else { list.join(" ") }; println!("{what}: {shown}"); Ok(list) } /// The version the file `file` holds, as JSON the federation takes. fn version_in(file: &str) -> Result { let text = std::fs::read_to_string(file).with_context(|| format!("Reading {file}"))?; let version: JsonValue = serde_json::from_str(&text).with_context(|| format!("{file} isn't JSON"))?; client::json(&version).map_err(|why| anyhow!(why)) } /// `bytes`, to standard output. fn out(bytes: &[u8]) -> Result<()> { use std::io::Write; let mut stdout = std::io::stdout().lock(); stdout.write_all(bytes)?; stdout.flush()?; Ok(()) } fn strings(matches: &ArgMatches, name: &str) -> Vec { matches .get_many::(name) .into_iter() .flatten() .cloned() .collect() } /// What `--key` gives: a private key, from an OpenSSH private key file; or a public key, /// given itself (an `authorized_keys` line), or the first of a file of such lines, with /// how many more the file holds. enum Given { Private(SigningKey), Public(Key, usize), } /// What `given`, `--key`'s value, gives (`Given`). fn given_key(given: &str) -> Result { let itself = match Key::parse(given) { Ok(key) => return Ok(Given::Public(key, 0)), Err(why) => why, }; let text = match std::fs::read_to_string(given) { Ok(text) => text, Err(error) if error.kind() == std::io::ErrorKind::NotFound => { bail!("{given}: no file, nor a key ({itself})") } Err(error) => return Err(error).with_context(|| format!("Reading {given}")), }; if text.trim_start().starts_with("-----BEGIN") { let key = client::signing_key(&text).map_err(|why| anyhow!("{given}: {why}"))?; return Ok(Given::Private(key)); } let mut lines = text .lines() .map(str::trim) .filter(|line| !line.is_empty() && !line.starts_with('#')); let first = lines .next() .with_context(|| format!("{given} holds no key"))?; let key = Key::parse(first).map_err(|why| anyhow!("{given}: {why}"))?; Ok(Given::Public(key, lines.count())) } /// The key `--key` gives (`given_key`): a private key, signing here; or a public key, /// signing through the ssh-agent at `SSH_AUTH_SOCK`, which must hold it. Of a file of /// several public keys, the first, with a warning: another is given as `--key` itself. fn signing_key(options: &Options) -> Result { let given = options .key .as_ref() .context("--key names the party's key")?; let key = match given_key(given)? { Given::Private(key) => return Ok(Signing::File(key)), Given::Public(key, 0) => key, Given::Public(key, more) => { eprintln!( "Warning: {given} holds {} keys: signing with the first, {}; to sign with \ another, give that key itself as --key", more + 1, key.line() ); key } }; let socket = std::env::var_os("SSH_AUTH_SOCK").with_context(|| { format!( "{} signs through an ssh-agent: SSH_AUTH_SOCK names none", key.line() ) })?; Ok(Signing::Agent(key, PathBuf::from(socket))) } /// What signs: a key at hand, or a key the ssh-agent at a socket holds. enum Signing { File(SigningKey), Agent(Key, PathBuf), } /// Who signs: the party, with one of its keys. struct Signer { key: Signing, party: String, } impl Signer { /// The key it signs with, as the federation spells it. fn line(&self) -> String { match &self.key { Signing::File(key) => PublicKey(key.verifying_key().to_bytes()).line(), Signing::Agent(key, _) => key.line(), } } /// Refuses where `current` doesn't name the key it signs with for its party: only those /// sign the party's votes, proposals, key set and node list, and otherwise only a /// version naming the party's keys or list anew, by the parties' votes, changes them. fn named_by(&self, current: &Version) -> Result<()> { let (party, number) = (&self.party, current.number); let Some(given) = current.parties.get(party) else { bail!( "{party} is no party of version {number}: only a version letting it in names its \ keys and node list, which a party of it proposes and the parties pass" ); }; if !given.keys.contains(&self.line()) { bail!( "version {number} doesn't name the key --key gives for {party}: only the keys it \ names sign {party}'s votes, proposals, key set and node list. A version naming \ its keys or its list anew changes them: another party proposes it \ (continuum-party next, then propose), and the parties pass it" ); } Ok(()) } fn sign(&self, deps: &[Id], does: (&str, Json)) -> Result> { match &self.key { Signing::File(key) => Ok(event::signed(key, &self.party, &self.line(), deps, does)), Signing::Agent(key, socket) => { // The agent's answer is waited for blocking the thread, in async code: the // client signs one event at a time and does nothing else meanwhile, and an // agent may wait for its user (a touch, a confirmation) as long as that // takes, which nothing here should cut short. event::signed_by(&self.party, &key.line(), deps, does, |bytes| { keys::sign_through(socket, key, bytes) }) .map_err(|why| anyhow!(why)) } } } } /// An event signed on the node's heads, recorded, and put. async fn sign( node: &Node, signer: &Signer, record: &mut Record, path: &Path, does: (&str, Json), ) -> Result<()> { let (_, heads) = node.summary().await?; let event = signer.sign(&heads, does)?; record.signed(&event); record.save(path).map_err(|why| anyhow!(why))?; node.put(&event).await } /// A vote, by the record: written to it before it is sent. async fn vote( node: &Node, signer: &Signer, record: &mut Record, path: &Path, proposal: Id, yes: bool, ) -> Result<()> { let counts = node.counts().await?; let current = current(&counts)?; signer.named_by(¤t)?; let ballots = &counts["proposals"]; let ids = |hash: &Id, what: &str| -> Vec { ballots[hash.to_string()][what] .as_array() .into_iter() .flatten() .filter_map(|id| id.as_str().and_then(Id::from_hex)) .collect() }; let proposals = ids(&proposal, "proposals"); let Some(proposing) = proposals.first().copied() else { if let Some(why) = ballots[proposal.to_string()]["none"].as_str() { bail!("{proposal}: {why}"); } bail!("no proposal of hash {proposal} on the current version, as the node reads it"); }; let proposed = match Event::read(&node.event(&proposing).await?) { Some(Event::Signed(Signed { does: Does::Proposal { hash, version }, .. })) if hash == proposal => version, _ => bail!("the node's {proposing} isn't the proposal it names"), }; // A later revision: the node knows it, or it stops at the version once it passes; and // so does every other node not known to know it. if yes && let Ok(version) = Version::read(&proposed) && version.revision != current.revision { if !node.revisions().await?.contains(&version.revision.id()) { bail!( "{proposal} moves to {}, which the node doesn't know: once it passed, a node \ that doesn't stops at it, and votes nothing till upgraded; upgrade this node \ and every other of the party to a continuum that knows it, then back it", version.revision ); } warn_unready(&counts, version.revision); } // The votes on its party's earlier proposals it backed, for the nays among them. let mut nays = Vec::new(); let backed: BTreeSet = record .votes .iter() .filter_map(|text| match Event::read_taken(text.as_bytes()) { Some(Event::Signed(Signed { does: Does::Vote { on, proposal, yes: true, }, .. })) if on == current.hash => Some(proposal), _ => None, }) .collect(); for earlier in &backed { for id in ids(earlier, "votes") { nays.push(node.event(&id).await?); } } let kept = record .may_vote(¤t, proposal, &proposed, yes, &nays) .map_err(|why| anyhow!(why))?; if yes { let parties = |what: &str| -> BTreeSet { ballots[proposal.to_string()][what] .as_array() .into_iter() .flatten() .filter_map(|party| party.as_str().map(str::to_owned)) .collect() }; if let Some(why) = client::binding(¤t, &signer.party, &parties("yes"), &parties("no")) { eprintln!("Warning: {why}"); } } // On the events proposing it the node shows, those above the heads it names for a // checkpoint, so a version event may be written on it. let cast = signer.sign(&proposals, event::vote(current.hash, proposal, yes))?; record.cast(¤t, &cast, kept); record.save(path).map_err(|why| anyhow!(why))?; node.put(&cast).await } /// Warns of the nodes not known to know `revision`, by `counts` (`client::unready`). fn warn_unready(counts: &JsonValue, revision: Revision) { let behind = client::unready(counts, revision); if behind.is_empty() { return; } eprintln!( "Warning: these nodes aren't known to know {revision}, as far as the node heard from \ them; once a version of it passes, each stops at it till upgraded:" ); for line in behind { eprintln!(" {line}"); } } /// Signs again what a move refused: of the latest event it signed at each place, its key /// set and its node list, those the node refuses as not above its checkpoint's heads, or /// as built on one it refuses. async fn again(node: &Node, signer: &Signer, record: &mut Record, path: &Path) -> Result<()> { let refused = node.get("/events/refused").await?; let moved: BTreeSet = refused["refused"] .as_array() .into_iter() .flatten() .filter(|entry| matches!(entry["kind"].as_str(), Some("notAbove" | "builtOn"))) .filter_map(|entry| entry["id"].as_str().and_then(Id::from_hex)) .collect(); let again = record.again(|id| moved.contains(id)); if again.is_empty() { println!("nothing to sign again"); } for (refused, does) in again { let does = match does { Does::Write { path, value } => event::write(&path.join("/"), value), Does::Keys(keys) => event::keys(&keys), Does::Nodes(nodes) => event::nodes(&nodes), Does::Proposal { .. } | Does::Vote { .. } | Does::Merge => continue, }; println!("signing again {refused}"); sign(node, signer, record, path, does).await?; } Ok(()) } /// The proposals on the current version at `node`, each with whether it passed or is dead, /// who voted what, and what its version changes, as one of the events proposing it holds /// it. async fn proposals(node: &Node) -> Result<()> { let counts = node.counts().await?; let current = current(&counts)?; let parties = |names: &JsonValue| -> String { let names: Vec<&str> = names .as_array() .into_iter() .flatten() .filter_map(JsonValue::as_str) .collect(); if names.is_empty() { "nobody".to_owned() } else { names.join(", ") } }; for (hash, proposal) in counts["proposals"].as_object().into_iter().flatten() { let standing = match (proposal["passed"].as_bool(), proposal["dead"].as_bool()) { (Some(true), _) => "passed", (_, Some(true)) => "dead", _ => "can still pass", }; println!( "{hash}: {standing}; true: {}; false: {}", parties(&proposal["yes"]), parties(&proposal["no"]) ); let Some(id) = proposal["proposals"][0].as_str() else { if let Some(why) = proposal["none"].as_str() { println!(" backed by no client: {why}"); } continue; }; let id = Id::from_hex(id).ok_or_else(|| anyhow!("the node names no event ID: {id}"))?; match Event::read(&node.event(&id).await?) { Some(Event::Signed(Signed { does: Does::Proposal { hash: of, version }, .. })) if of.to_string() == *hash => { if let Err(why) = client::backable(¤t, &version) { println!(" backed by no client: {why}"); } for line in client::changes(¤t.json, &version) { println!(" {line}"); } } _ => println!(" the event {id} proposes no version of that hash"), } } Ok(()) } /// The version after `current`, to change and propose: `current` numbered on, naming its /// hash as the version it changes, and without the checkpoint it names, whose heads are /// behind: a version naming them again is never written. With `feature`, following the /// revision that adds it, where that isn't earlier than the current one's. fn next(current: &Version, feature: Option<&str>) -> Result { let mut next: JsonValue = serde_json::from_slice(¤t.json.bytes())?; let fields = next .as_object_mut() .context("a version that is no object")?; fields.insert("number".to_owned(), (current.number + 1).into()); fields.insert("changes".to_owned(), current.hash.to_string().into()); fields.remove("checkpoint"); if let Some(name) = feature { let Some(feature) = FEATURES.iter().find(|feature| feature.name() == name) else { let names: Vec<&str> = FEATURES.iter().map(|feature| feature.name()).collect(); bail!( "no feature {name:?} this continuum knows: it knows {}", if names.is_empty() { "none".to_owned() } else { names.join(", ") } ); }; let revision = feature.revision(); if revision < current.revision { bail!( "the current version follows {}, later than {revision}: a version never \ follows an earlier revision than the one it changes", current.revision ); } fields.insert("revision".to_owned(), revision.id().to_string().into()); } Ok(next) } /// The current version, as `counts` names it, checked: its hash its own. fn current(counts: &JsonValue) -> Result { let json = client::json(&counts["version"]["version"]).map_err(|why| anyhow!(why))?; let version = Version::read(&json).map_err(|why| anyhow!("the node's current version: {why}"))?; if Some(version.hash.to_string().as_str()) != counts["version"]["hash"].as_str() { bail!("the node's current version isn't of the hash it names"); } Ok(version) } /// A node's API. struct Node { url: reqwest::Url, http: reqwest::Client, password: Option<(String, Option)>, token: Option, } impl Node { fn new(options: &Options) -> Result { let _ = rustls::crypto::ring::default_provider().install_default(); let mut url: reqwest::Url = options.node.parse().context("--node isn't a URL")?; let password = (!url.username().is_empty()) .then(|| (url.username().to_owned(), url.password().map(str::to_owned))); let _ = url.set_username(""); let _ = url.set_password(None); Ok(Node { url, http: reqwest::Client::new(), password, token: options.token.clone(), }) } fn request(&self, method: reqwest::Method, path: &str) -> Result { let url = self.url.join(path).context("a path of the node's API")?; let request = self.http.request(method, url); Ok(match (&self.token, &self.password) { (Some(token), _) => request.bearer_auth(token), (None, Some((user, password))) => request.basic_auth(user, password.as_ref()), (None, None) => request, }) } async fn answer(response: reqwest::Response) -> Result { let status = response.status(); if status.is_success() { return Ok(response); } let body = response.text().await.unwrap_or_default(); bail!("the node answers {status}: {body}") } async fn get(&self, path: &str) -> Result { let response = self.request(reqwest::Method::GET, path)?.send().await?; Ok(Self::answer(response).await?.json().await?) } /// The store's ID, and its heads. async fn summary(&self) -> Result<(Id, Vec)> { let summary = self.get("/events").await?; let store = summary["store"] .as_str() .and_then(Id::from_hex) .context("the node names no store")?; let heads = summary["heads"] .as_array() .into_iter() .flatten() .filter_map(|id| id.as_str().and_then(Id::from_hex)) .collect(); Ok((store, heads)) } async fn counts(&self) -> Result { self.get("/events/counts").await } async fn current(&self) -> Result { current(&self.counts().await?) } /// The IDs of the revisions the node knows: none where it says none, as one too old to /// know the base revision by name. async fn revisions(&self) -> Result> { let summary = self.get("/events").await?; Ok(summary["revisions"] .as_array() .into_iter() .flatten() .filter_map(|revision| revision["id"].as_str().and_then(Id::from_hex)) .collect()) } /// The bytes of an event the node's store holds. async fn event(&self, id: &Id) -> Result> { let response = self .request(reqwest::Method::GET, &format!("/events/{id}"))? .send() .await?; let bytes = Self::answer(response).await?.bytes().await?.to_vec(); if Id::of(&bytes) != *id { bail!("the node's event {id} isn't of that ID"); } Ok(bytes) } async fn post(&self, path: &str, body: &JsonValue) -> Result { let response = self .request(reqwest::Method::POST, path)? .json(body) .send() .await?; Ok(Self::answer(response).await?.json().await?) } /// What the node answers to `body`, as bytes. async fn post_for_bytes(&self, path: &str, body: &JsonValue) -> Result> { let response = self .request(reqwest::Method::POST, path)? .json(body) .send() .await?; Ok(Self::answer(response).await?.bytes().await?.to_vec()) } /// What the node answers to the bytes `body`. async fn post_bytes(&self, path: &str, body: Vec) -> Result { let response = self .request(reqwest::Method::POST, path)? .header(reqwest::header::CONTENT_TYPE, "application/octet-stream") .body(body) .send() .await?; Ok(Self::answer(response).await?.json().await?) } async fn put(&self, event: &[u8]) -> Result<()> { let response = self .request(reqwest::Method::POST, "/events")? .header(reqwest::header::CONTENT_TYPE, "application/json") .body(event.to_vec()) .send() .await?; let answer: JsonValue = Self::answer(response).await?.json().await?; println!( "{} {}", answer["id"].as_str().unwrap_or_default(), answer["event"].as_str().unwrap_or_default() ); Ok(()) } } #[cfg(test)] mod tests { #[test] fn its_arguments_are_well_formed() { super::command().debug_assert(); } /// `--key` gives a public key itself, or the first of a file's with how many more it /// holds, or a private key file's key; a file of neither, or none, gives nothing. #[test] fn the_key_given() { use super::{Given, given_key}; use crate::federation::vectors::ECDSA_KEY; let ed25519 = crate::federation::harness::key_line(1); let dir = crate::files::scratch_dir("party-key"); let file = |name: &str, text: &str| { let path = dir.join(name); std::fs::write(&path, text).unwrap(); path.to_str().unwrap().to_owned() }; let public = |given: &str| match given_key(given).unwrap() { Given::Public(key, more) => (key.line(), more), Given::Private(_) => panic!("{given}: a private key"), }; assert_eq!(public(ECDSA_KEY), (ECDSA_KEY.to_owned(), 0)); assert_eq!( public(&format!("{ed25519} tv@laptop")), (ed25519.clone(), 0) ); let one = file("phone.pub", &format!("{ECDSA_KEY} tv@phone\n")); assert_eq!(public(&one), (ECDSA_KEY.to_owned(), 0)); let two = file( "agent.pub", &format!("{ed25519} tv@laptop\n\n{ECDSA_KEY} tv@phone\n"), ); assert_eq!(public(&two), (ed25519, 1)); assert!(given_key(&file("rsa.pub", "ssh-rsa AAAAB3NzaC1yc2E tv\n")).is_err()); assert!(given_key(&file("empty.pub", "\n")).is_err()); assert!(given_key(dir.join("missing").to_str().unwrap()).is_err()); let private = file( "tv.key", "-----BEGIN OPENSSH PRIVATE KEY-----\n-----END OPENSSH PRIVATE KEY-----\n", ); let why = given_key(&private).err().expect("no key").to_string(); assert!(why.contains("OpenSSH private key"), "{why}"); } /// A key set or node list changed as it counts: each item added absent, each taken off /// held; set whole, it is as set, none twice; left empty only by force. #[test] fn a_list_changed_as_it_counts() { use super::changed; let list = |items: &[&str]| -> Vec { items.iter().map(|item| (*item).to_owned()).collect() }; let now = list(&["a", "b"]); let changed_by = |set: Option<&[&str]>, add: &[&str], remove: &[&str], force: bool| { let set = set.map(list); let (add, remove) = (list(add), list(remove)); changed( now.clone(), set, add, remove, force, "tv's list", "nothing left", ) }; assert_eq!( changed_by(Some(&["c"]), &[], &[], false).unwrap(), list(&["c"]) ); assert_eq!( changed_by(None, &["c"], &["a"], false).unwrap(), list(&["b", "c"]) ); assert!(changed_by(None, &["a"], &[], false).is_err()); assert!(changed_by(None, &[], &["c"], false).is_err()); assert!(changed_by(Some(&["c", "c"]), &[], &[], false).is_err()); assert!(changed_by(None, &[], &["a", "b"], false).is_err()); assert!(changed_by(Some(&[]), &[], &[], false).is_err()); assert_eq!(changed_by(None, &[], &["a", "b"], true).unwrap(), list(&[])); assert_eq!(changed_by(Some(&[]), &[], &[], true).unwrap(), list(&[])); } /// Votes, proposals, key sets and node lists are signed with a key the current version /// names for their party; another key, or a party the version doesn't have, is refused /// before signing. #[test] fn what_only_a_versions_keys_sign_is_signed_with_one() { use super::{Signer, Signing}; use crate::federation::harness::{Party, Spec}; use crate::federation::version::Version; let (tv, lass) = (Party::new("tv", 1), Party::new("lass", 2)); let current = Version::read(&Spec::first(&[&tv, &lass], &[]).json()).unwrap(); let signer = |key: &Party, party: &str| Signer { key: Signing::File(key.key.clone()), party: party.to_owned(), }; assert!(signer(&tv, "tv").named_by(¤t).is_ok()); assert!(signer(&lass, "tv").named_by(¤t).is_err()); let makefu = Party::new("makefu", 3); assert!(signer(&makefu, "makefu").named_by(¤t).is_err()); } /// The next version is the current one numbered on, naming its hash, without its /// checkpoint: a version changing it, as its parties may pass. With a feature, it /// follows the revision adding it, never an earlier one than the current version's. #[test] fn the_next_version_changes_the_current_one() { use crate::federation::harness::{Party, Spec}; use crate::federation::revision::{Feature, Revision}; use crate::federation::store::Id; use crate::federation::version::Version; let first = Spec::first(&[&Party::new("tv", 1), &Party::new("lass", 2)], &[]); let mut second = first.after(first.hash()); second.checkpoint = Some(vec![Id::of(b"a head")]); let current = Version::read(&second.json()).unwrap(); let next = super::next(¤t, None).unwrap(); assert_eq!(next["number"], current.number + 1); assert_eq!(next["changes"], current.hash.to_string()); assert!(next.get("checkpoint").is_none()); assert!(next.get("revision").is_none()); let next = Version::read(&crate::federation::client::json(&next).unwrap()).unwrap(); next.changes_validly(Some(¤t)).unwrap(); let revised = super::next(¤t, Some("merge-events")).unwrap(); let revised = Version::read(&crate::federation::client::json(&revised).unwrap()).unwrap(); assert_eq!(revised.revision, Feature::MergeEvents.revision()); revised.changes_validly(Some(¤t)).unwrap(); // Kept on, where nothing is said. let kept = super::next(&revised, None).unwrap(); let kept = Version::read(&crate::federation::client::json(&kept).unwrap()).unwrap(); assert_eq!(kept.revision, revised.revision); let why = super::next(¤t, Some("elsewhere")) .unwrap_err() .to_string(); assert!(why.contains("merge-events"), "{why}"); assert_ne!(revised.revision, Revision::default()); } /// Its options come from configuration files as the node's do, arguments winning. #[test] fn its_options_come_from_configuration_files_and_arguments() { use crate::config; let dir = crate::files::scratch_dir("party-config"); let file = dir.join("party.toml"); std::fs::write( &file, "node = \"http://tv:secret@localhost:3001\"\nkey = \"tv.key\"\nrecord = \"tv.record\"\n", ) .unwrap(); let path = file.to_str().unwrap(); let matches = super::command() .try_get_matches_from([ "continuum-party", "--config", path, "--key", "laptop.key", "proposals", ]) .unwrap(); let (merged, _) = config::merged(&matches, config::PARTY_OPTIONS).unwrap(); let options: super::Options = config::read(&merged).unwrap(); assert_eq!(options.node, "http://tv:secret@localhost:3001"); assert_eq!(options.key.as_deref(), Some("laptop.key")); assert_eq!(options.record.as_deref(), Some("tv.record")); assert_eq!(options.token, None); // A key naming none of the client's options is an error, as in the node's files. std::fs::write(&file, "bind-addr = \"127.0.0.1:3000\"\n").unwrap(); assert!(config::merged(&matches, config::PARTY_OPTIONS).is_err()); } }