//! `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), 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 KEY...`, `nodes NODE...`: writes the party's key set (`authorized_keys` lines, //! each one argument, their comments left out) or node list (node IDs); //! * `propose FILE`: proposes the version `FILE` holds (JSON); //! * `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. use std::collections::BTreeSet; use std::path::{Path, PathBuf}; use anyhow::{Context, Result, anyhow, bail}; use clap::{Arg, ArgAction, 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::keys::{self, Key}; 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") .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("Writes the party's key set") .arg(Arg::new("keys").num_args(1..).required(true)), ) .subcommand( Command::new("nodes") .about("Writes the party's node list") .arg(Arg::new("nodes").num_args(0..)), ) .subcommand( Command::new("propose") .about("Proposes the version a file holds (JSON)") .arg(id("file")), ) .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("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), ), ) } /// 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, &[])); } let node = Node::new(&options)?; if name == "proposals" { return proposals(&node).await; } 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))?; 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 keys = strings(sub, "keys") .iter() .map(|line| { Key::parse(line) .map(|key| key.line()) .map_err(|why| anyhow!("{line:?}: {why}")) }) .collect::>>()?; sign(&node, &signer, &mut record, &path, event::keys(&keys)).await } ("nodes", sub) => { let nodes: Vec = strings(sub, "nodes"); sign(&node, &signer, &mut record, &path, event::nodes(&nodes)).await } ("propose", sub) => { let version = version_in(sub.get_one::("file").expect("required"))?; sign( &node, &signer, &mut record, &path, event::proposal(&version), ) .await } ("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 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() } /// The key `--key` names: a private key file's, or a public key's, held by the ssh-agent. fn signing_key(options: &Options) -> Result { let file = options .key .as_ref() .context("--key names the party's key")?; let text = std::fs::read_to_string(file).with_context(|| format!("Reading {file}"))?; if let Ok(key) = Key::parse(&text) { let socket = std::env::var_os("SSH_AUTH_SOCK").with_context(|| { format!( "{file} is a public key, signed with through an ssh-agent: SSH_AUTH_SOCK names none" ) })?; return Ok(Signing::Agent(key, PathBuf::from(socket))); } let key = client::signing_key(&text).map_err(|why| anyhow!("{file}: {why}"))?; Ok(Signing::File(key)) } /// 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 { fn sign(&self, deps: &[Id], does: (&str, Json)) -> Result> { match &self.key { Signing::File(key) => { let line = PublicKey(key.verifying_key().to_bytes()).line(); Ok(event::signed(key, &self.party, &line, deps, does)) } Signing::Agent(key, socket) => { 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)?; 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 { 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"), }; // 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))?; // On the events proposing it: above the heads it names for a checkpoint wherever they // are, 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 } /// 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 { .. } => 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 { 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 => { for line in client::changes(¤t.json, &version) { println!(" {line}"); } } _ => println!(" the event {id} proposes no version of that hash"), } } Ok(()) } /// 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 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(); } /// 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()); } }