aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-18 12:31:09 +0000
committertv <tv@krebsco.de>2026-11-18 13:34:43 +0100
commit13d96ce6ecd386ddd39b803ecb52a8557476f8fa (patch)
tree3b1b946457dbb6073119a7be1b35d7d57934c804
parent114739426a34654f1d296ed38040e369737775b2 (diff)
continuum-party keys, nodes: shown given no change, --set, --force
`keys` and `nodes` alone (`--list`) show the party's key set or node list as it counts at the node, one a line, without a key. `--set` writes it whole, none twice, in place of the arguments that did; `--add` and `--remove` change it as it counts. A set or list left empty, whichever way (`--set` with none, `--remove` of the last), is written with `--force` only: none of the party's writes count without keys, nor its nodes as members without a list.
-rw-r--r--docs/guides/federation/common-changes.md10
-rw-r--r--docs/guides/federation/keys.md17
-rw-r--r--docs/guides/federation/running-a-node.md2
-rw-r--r--docs/guides/federation/when-things-go-wrong.md4
-rw-r--r--src/federation/party.rs156
5 files changed, 128 insertions, 61 deletions
diff --git a/docs/guides/federation/common-changes.md b/docs/guides/federation/common-changes.md
index 1f7f331..1dd30c1 100644
--- a/docs/guides/federation/common-changes.md
+++ b/docs/guides/federation/common-changes.md
@@ -86,8 +86,9 @@ jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" '
## What a party does by itself
-* **Its node list**, signed with a key its version names, no vote: the list whole, or the
- list as it counts at the node with nodes added (`--add`) or taken off (`--remove`):
+* **Its node list**, signed with a key its version names, no vote: the list as it counts
+ at the node with nodes added (`--add`) or taken off (`--remove`), or set whole
+ (`--set`); `nodes` alone shows it:
```sh
continuum-party --node http://tv:secret@localhost:3000 --key tv.key \
@@ -96,8 +97,9 @@ jq --arg key "$(cut -d' ' -f1,2 tv-new.key.pub)" '
# 9b2c… taken
```
- The client checks first that the current version names the key it signs with for the
- party, and says otherwise: then only a version naming the party's keys or its list
+ A list left empty, taking all of the party's nodes out of the swarm, is written with
+ `--force` only. The client checks first that the current version names the key it
+ signs with for the party, and says otherwise: then only a version naming the party's keys or its list
anew changes it, which a party proposes and the parties pass. A version names a
party's list anew only where it must: when the party is let in, or when it can't write
its own.
diff --git a/docs/guides/federation/keys.md b/docs/guides/federation/keys.md
index 6f9fc10..7f5bd7a 100644
--- a/docs/guides/federation/keys.md
+++ b/docs/guides/federation/keys.md
@@ -18,16 +18,17 @@ So keep the keys a version names apart, offline, on one machine with the party's
```sh
ssh-keygen -t ed25519 -N '' -f laptop.key
continuum-party --node http://tv:secret@localhost:3000 --key tv.key --record tv.record \
- keys "$(cat laptop.key.pub)" "$(cat desk.key.pub)"
+ keys --set "$(cat laptop.key.pub)" "$(cat desk.key.pub)"
continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \
--record tv.record write home/tv/motd '"from the laptop"'
```
-Each key goes as one argument, an `authorized_keys` line; its comment is left out. With
-`--add` and `--remove` instead, the client writes the set as it counts at the node with
-those keys added or taken off (`keys --add "$(cat phone.pub)"`). A set holds up to 16
-keys, signed with a key the current version names for the party, which the client checks
-first. A node voting by itself keeps a key its version names on that
+Each key goes as one argument, an `authorized_keys` line; its comment is left out.
+`--set` writes the set whole; `--add` and `--remove` write it as it counts at the node,
+with those keys added or taken off (`keys --add "$(cat phone.pub)"`); `keys` alone shows
+it. A set left empty, so that none of the party's writes count, is written with
+`--force` only. A set holds up to 16 keys, signed with a key the current version names
+for the party, which the client checks first. A node voting by itself keeps a key its version names on that
node (`--store-vote-key`), an Ed25519 key in a file: one stolen there votes for the
party.
@@ -69,7 +70,7 @@ A write counts only while the key that signed it is among the party's keys: what
signed counts no more once the party's set drops it, wherever in history it is. So
before dropping a key, sign again with a new one what should stay:
-1. Write a set with the new keys beside the old.
+1. Add the new keys to the set, beside the old (`keys --add`).
2. Write again, with a new key, every value the party wants kept, on heads that hold that
set (the client signs on the heads its node shows). For a namespace:
@@ -82,7 +83,7 @@ before dropping a key, sign again with a new one what should stay:
done
```
-3. Write a set without the old keys.
+3. Take the old keys off the set (`keys --remove`).
A key added back, from a backup say, brings back what it signed, where nothing the party
signed since replaced it and no checkpoint left it out.
diff --git a/docs/guides/federation/running-a-node.md b/docs/guides/federation/running-a-node.md
index 371bd10..a423376 100644
--- a/docs/guides/federation/running-a-node.md
+++ b/docs/guides/federation/running-a-node.md
@@ -52,7 +52,7 @@ with it (`This node is a member of its store`). A party that takes a node off it
takes it out of the swarm.
A party writes its node list itself, without a vote, signed with a key its version names
-(`continuum-party nodes`,
+(`continuum-party nodes --add`,
[`common-changes.md`](common-changes.md#what-a-party-does-by-itself)): a node it adds
is a member as soon as the list is taken.
diff --git a/docs/guides/federation/when-things-go-wrong.md b/docs/guides/federation/when-things-go-wrong.md
index e4a3b81..de2e34a 100644
--- a/docs/guides/federation/when-things-go-wrong.md
+++ b/docs/guides/federation/when-things-go-wrong.md
@@ -71,8 +71,8 @@ record.
document (yet)`), or its document's root is no store's (`The document's root is no
store's: not reading it`).
* **Nobody syncs with it** (`This node isn't a member of its store`): its party's node
- list doesn't name it, as the store reads now. The party writes its list
- (`continuum-party nodes`), through any member.
+ list doesn't name it, as the store reads now. The party adds it to its list
+ (`continuum-party nodes --add`), through any member.
* **An event waits** (`waiting` when put): the node lacks an event it builds on. It
takes it once that one arrives.
* **It doesn't start**: its store file doesn't read, or an option of a swarm that isn't
diff --git a/src/federation/party.rs b/src/federation/party.rs
index 9a74556..788bde9 100644
--- a/src/federation/party.rs
+++ b/src/federation/party.rs
@@ -10,9 +10,10 @@
//! 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); with `--add` and
-//! `--remove`, the set or list as it counts at the node, changed;
+//! * `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 it changes the
@@ -43,7 +44,7 @@ use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
use anyhow::{Context, Result, anyhow, bail};
-use clap::{Arg, ArgAction, ArgMatches, Command};
+use clap::{Arg, ArgAction, ArgGroup, ArgMatches, Command};
use ed25519_dalek::SigningKey;
use serde::Deserialize;
use serde_json::Value as JsonValue;
@@ -100,24 +101,21 @@ fn command() -> Command {
)
.subcommand(
Command::new("keys")
- .about("Writes the party's key set: these keys, or the set as it counts, changed")
- .arg(
- Arg::new("keys")
- .num_args(1..)
- .required_unless_present_any(["add", "remove"])
- .conflicts_with_all(["add", "remove"]),
+ .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")),
+ .args(changing("KEY", "keys", "key set"))
+ .group(changes()),
)
.subcommand(
Command::new("nodes")
- .about("Writes the party's node list: these nodes, or the list as it counts, changed")
- .arg(
- Arg::new("nodes")
- .num_args(0..)
- .conflicts_with_all(["add", "remove"]),
+ .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")),
+ .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 \
@@ -179,17 +177,27 @@ fn command() -> Command {
)
}
-/// `--add` and `--remove`, of the party's key set or node list as it counts: `what`, of
-/// values named `value`.
-fn changing(value: &'static str, what: &str) -> [Arg; 2] {
+/// 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 {what} to the party's, as they count at the node"
+ "Adds these {items} to the party's {whole}, as it counts at the node"
)),
Arg::new("remove")
.long("remove")
@@ -197,11 +205,32 @@ fn changing(value: &'static str, what: &str) -> [Arg; 2] {
.num_args(1..)
.action(ArgAction::Append)
.help(format!(
- "Takes these {what} off the party's, as they count at the node"
+ "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();
@@ -316,6 +345,13 @@ pub(crate) async fn main() -> Result<()> {
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,
@@ -351,12 +387,15 @@ pub(crate) async fn main() -> Result<()> {
};
let counts = node.counts().await?;
signer.named_by(&current(&counts)?)?;
+ let party = &signer.party;
let keys = changed(
- listed(&counts, &signer.party, "keys"),
- spelled("keys")?,
+ listed(&counts, party, "keys"),
+ sub.contains_id("set").then(|| spelled("set")).transpose()?,
spelled("add")?,
spelled("remove")?,
- &format!("{}'s key set", signer.party),
+ 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
}
@@ -370,12 +409,15 @@ pub(crate) async fn main() -> Result<()> {
};
let counts = node.counts().await?;
signer.named_by(&current(&counts)?)?;
+ let party = &signer.party;
let nodes = changed(
- listed(&counts, &signer.party, "nodes"),
- given("nodes")?,
+ listed(&counts, party, "nodes"),
+ sub.contains_id("set").then(|| given("set")).transpose()?,
given("add")?,
given("remove")?,
- &format!("{}'s node list", signer.party),
+ 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
}
@@ -423,21 +465,26 @@ fn listed(counts: &JsonValue, party: &str, what: &str) -> Vec<String> {
.collect()
}
-/// The key set or node list to write: `given` where neither `add` nor `remove` names any,
-/// else `now`, as it counts, with `add` added and `remove` taken off, each of which must
-/// change it (`what` names it in the error otherwise). Said where it is changed, before it
+/// 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<String>,
- given: Vec<String>,
+ set: Option<Vec<String>>,
add: Vec<String>,
remove: Vec<String>,
+ force: bool,
what: &str,
+ empty: &str,
) -> Result<Vec<String>> {
- if add.is_empty() && remove.is_empty() {
- return Ok(given);
+ 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);
}
- let mut list = now;
for item in add {
if list.contains(&item) {
bail!("{what} holds {item} already");
@@ -450,6 +497,9 @@ fn changed(
};
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 {
@@ -974,8 +1024,8 @@ mod tests {
assert!(why.contains("OpenSSH private key"), "{why}");
}
- /// A key set or node list changed as it counts: each name added absent, each taken off
- /// held; named whole, it is as named.
+ /// 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;
@@ -983,20 +1033,34 @@ mod tests {
items.iter().map(|item| (*item).to_owned()).collect()
};
let now = list(&["a", "b"]);
- let changed_by = |given: &[&str], add: &[&str], remove: &[&str]| {
+ 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(),
- list(given),
- list(add),
- list(remove),
+ set,
+ add,
+ remove,
+ force,
"tv's list",
+ "nothing left",
)
};
- assert_eq!(changed_by(&["c"], &[], &[]).unwrap(), list(&["c"]));
- assert_eq!(changed_by(&[], &["c"], &["a"]).unwrap(), list(&["b", "c"]));
- assert_eq!(changed_by(&[], &[], &["a", "b"]).unwrap(), list(&[]));
- assert!(changed_by(&[], &["a"], &[]).is_err());
- assert!(changed_by(&[], &[], &["c"]).is_err());
+ 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