aboutsummaryrefslogtreecommitdiffstats
path: root/src/federation/harness.rs
diff options
context:
space:
mode:
authortv <tv@krebsco.de>2026-11-16 17:55:32 +0000
committertv <tv@krebsco.de>2026-11-16 19:07:32 +0100
commitd61ebc07db70d9f03b1d74b03712cea9310b05a7 (patch)
treec6ac56c0c73af34b55918ddd53c147ab0a6345da /src/federation/harness.rs
parentb9da1b6b9a43dc4bfe1a6f99ea73342cf23c028c (diff)
federation: events and checkpoints as bytes, and a harness that signs them
`Event::read` reads an event and says what makes one none (`docs/federation.md`, Events): bytes that aren't the JCS of the JSON they read as, larger than 256 KiB, with no dependency or more than 64, not ascending, or a field missing or more; and of a signed event, a party that is no party's name, a key or signature that doesn't read back to itself or doesn't hold, a path, key set, node list or vote spelled otherwise. A proposal is taken whatever it holds, named by its hash; a version event names a hash. `Checkpoint` reads and writes `{"at", "keeps", "version"}`, a root among them, which is no event. The tests' harness (`docs/federation-tests.md`, The harness) makes parties with keys from seeds, signs each kind of event as the design says, and spells versions out.
Diffstat (limited to 'src/federation/harness.rs')
-rw-r--r--src/federation/harness.rs291
1 files changed, 291 insertions, 0 deletions
diff --git a/src/federation/harness.rs b/src/federation/harness.rs
new file mode 100644
index 0000000..6d1b214
--- /dev/null
+++ b/src/federation/harness.rs
@@ -0,0 +1,291 @@
+//! What the federation's tests build with (`docs/federation-tests.md`, The harness):
+//! parties with keys made from seeds, signing events as the design says, and versions.
+
+use ed25519_dalek::SigningKey;
+
+use super::jcs::Json;
+use super::keys;
+use super::store::Id;
+use crate::access::sshsig::PublicKey;
+
+/// A party of the tests: a name and a key, made from a seed.
+#[derive(Clone)]
+pub(crate) struct Party {
+ pub(crate) name: String,
+ pub(crate) key: SigningKey,
+}
+
+/// A key made from a seed, spelled as the federation spells one.
+pub(crate) fn key_line(seed: u8) -> String {
+ PublicKey(
+ SigningKey::from_bytes(&[seed; 32])
+ .verifying_key()
+ .to_bytes(),
+ )
+ .line()
+}
+
+/// A node ID made from a seed.
+pub(crate) fn node_id(seed: u8) -> String {
+ crate::identity::node_id_of(
+ &SigningKey::from_bytes(&[seed.wrapping_add(128); 32])
+ .verifying_key()
+ .to_bytes(),
+ )
+}
+
+pub(crate) fn str(text: &str) -> Json {
+ Json::Str(text.to_owned())
+}
+
+/// The JSON of IDs, as an event or a version names them.
+pub(crate) fn ids(ids: &[Id]) -> Json {
+ let mut ids = ids.to_vec();
+ ids.sort();
+ ids.dedup();
+ Json::Array(ids.iter().map(|id| Json::Str(id.to_string())).collect())
+}
+
+pub(crate) fn object(members: Vec<(&str, Json)>) -> Json {
+ Json::object(
+ members
+ .into_iter()
+ .map(|(name, value)| (name.to_owned(), value))
+ .collect(),
+ )
+ .expect("names once each")
+}
+
+impl Party {
+ pub(crate) fn new(name: &str, seed: u8) -> Party {
+ Party {
+ name: name.to_owned(),
+ key: SigningKey::from_bytes(&[seed; 32]),
+ }
+ }
+
+ /// Its key, spelled as the federation spells one.
+ pub(crate) fn key_line(&self) -> String {
+ PublicKey(self.key.verifying_key().to_bytes()).line()
+ }
+
+ /// An event it signs, on `deps`, doing `does` (a field's name, and what it holds), with
+ /// `key` its key, signed with `signer`: the two differ only where a test wants them to.
+ pub(crate) fn signed_as(
+ &self,
+ signer: &SigningKey,
+ key: &str,
+ deps: &[Id],
+ does: (&str, Json),
+ ) -> Vec<u8> {
+ let unsigned = object(vec![
+ ("deps", ids(deps)),
+ ("party", str(&self.name)),
+ ("key", str(key)),
+ (does.0, does.1),
+ ]);
+ let sig = keys::sign(signer, &unsigned.bytes());
+ let Json::Object(mut members) = unsigned else {
+ unreachable!("an object")
+ };
+ members.push(("sig".to_owned(), Json::Str(sig)));
+ Json::object(members).expect("names once each").bytes()
+ }
+
+ pub(crate) fn sign(&self, deps: &[Id], does: (&str, Json)) -> Vec<u8> {
+ self.signed_as(&self.key, &self.key_line(), deps, does)
+ }
+
+ pub(crate) fn write(&self, deps: &[Id], path: &str, value: Json) -> Vec<u8> {
+ self.sign(
+ deps,
+ ("write", object(vec![("path", str(path)), ("value", value)])),
+ )
+ }
+
+ pub(crate) fn keys(&self, deps: &[Id], keys: &[String]) -> Vec<u8> {
+ self.sign(
+ deps,
+ (
+ "keys",
+ Json::Array(keys.iter().map(|key| str(key)).collect()),
+ ),
+ )
+ }
+
+ pub(crate) fn nodes(&self, deps: &[Id], nodes: &[String]) -> Vec<u8> {
+ self.sign(
+ deps,
+ (
+ "nodes",
+ Json::Array(nodes.iter().map(|id| str(id)).collect()),
+ ),
+ )
+ }
+
+ pub(crate) fn propose(&self, deps: &[Id], version: &Json) -> Vec<u8> {
+ self.sign(deps, ("proposal", version.clone()))
+ }
+
+ pub(crate) fn vote(&self, deps: &[Id], on: Id, proposal: Id, yes: bool) -> Vec<u8> {
+ self.sign(
+ deps,
+ (
+ "vote",
+ object(vec![
+ ("on", str(&on.to_string())),
+ ("proposal", str(&proposal.to_string())),
+ ("yes", Json::Bool(yes)),
+ ]),
+ ),
+ )
+ }
+}
+
+/// A version event, which nobody signs.
+pub(crate) fn version_event(deps: &[Id], version: Id) -> Vec<u8> {
+ object(vec![
+ ("deps", ids(deps)),
+ ("version", str(&version.to_string())),
+ ])
+ .bytes()
+}
+
+/// What a version gives a party, as a test spells it out.
+#[derive(Clone)]
+pub(crate) struct SpecParty {
+ pub(crate) name: String,
+ pub(crate) keys_since: u64,
+ pub(crate) keys: Vec<String>,
+ pub(crate) nodes_since: u64,
+ pub(crate) nodes: Vec<String>,
+}
+
+/// A version, as a test spells it out.
+#[derive(Clone)]
+pub(crate) struct Spec {
+ pub(crate) number: u64,
+ pub(crate) changes: Option<Id>,
+ pub(crate) parties: Vec<SpecParty>,
+ /// Each rule: its path and its writer.
+ pub(crate) rules: Vec<(String, Json)>,
+ pub(crate) checkpoint: Option<Vec<Id>>,
+}
+
+impl Spec {
+ /// A first version naming these parties, each with its key and no nodes but the
+ /// first's, with a namespace each (`home/{party}/**`) and the rules given after.
+ pub(crate) fn first(parties: &[&Party], rules: &[(&str, Json)]) -> Spec {
+ Spec {
+ number: 0,
+ changes: None,
+ parties: parties
+ .iter()
+ .enumerate()
+ .map(|(i, party)| {
+ let nodes = if i == 0 { vec![node_id(0)] } else { Vec::new() };
+ SpecParty {
+ name: party.name.clone(),
+ keys_since: 0,
+ keys: vec![party.key_line()],
+ nodes_since: 0,
+ nodes,
+ }
+ })
+ .collect(),
+ rules: std::iter::once(("home/{party}/**".to_owned(), str("{party}")))
+ .chain(
+ rules
+ .iter()
+ .map(|(path, writer)| ((*path).to_owned(), writer.clone())),
+ )
+ .collect(),
+ checkpoint: None,
+ }
+ }
+
+ /// The version after `before`, which this spells: one past its number, changing its
+ /// hash, nothing named anew.
+ pub(crate) fn after(&self, before: Id) -> Spec {
+ Spec {
+ number: self.number + 1,
+ changes: Some(before),
+ checkpoint: None,
+ ..self.clone()
+ }
+ }
+
+ pub(crate) fn json(&self) -> Json {
+ let mut members = vec![
+ ("federation", Json::Int(1)),
+ ("number", Json::Int(self.number as i64)),
+ (
+ "changes",
+ self.changes
+ .map_or(Json::Null, |hash| Json::Str(hash.to_string())),
+ ),
+ (
+ "keys",
+ object(
+ self.parties
+ .iter()
+ .map(|party| {
+ (
+ party.name.as_str(),
+ object(vec![
+ ("since", Json::Int(party.keys_since as i64)),
+ (
+ "keys",
+ Json::Array(
+ party.keys.iter().map(|key| str(key)).collect(),
+ ),
+ ),
+ ]),
+ )
+ })
+ .collect(),
+ ),
+ ),
+ (
+ "nodes",
+ object(
+ self.parties
+ .iter()
+ .map(|party| {
+ (
+ party.name.as_str(),
+ object(vec![
+ ("since", Json::Int(party.nodes_since as i64)),
+ (
+ "nodes",
+ Json::Array(party.nodes.iter().map(|id| str(id)).collect()),
+ ),
+ ]),
+ )
+ })
+ .collect(),
+ ),
+ ),
+ (
+ "rules",
+ Json::Array(
+ self.rules
+ .iter()
+ .map(|(path, writer)| {
+ object(vec![("path", str(path)), ("writer", writer.clone())])
+ })
+ .collect(),
+ ),
+ ),
+ ];
+ if let Some(heads) = &self.checkpoint {
+ members.push(("checkpoint", ids(heads)));
+ }
+ object(members)
+ }
+
+ /// The version's hash.
+ pub(crate) fn hash(&self) -> Id {
+ Id::of(&self.json().bytes())
+ }
+}