From af120b87c42ca56f69bbe6f8d27c023919742430 Mon Sep 17 00:00:00 2001 From: tv Date: Sun, 15 Nov 2026 16:43:53 +0000 Subject: swarm: a new swarm's policy recorded in its genesis change A swarm strict from its start had its policy written by its first user in a later change. A change is judged by the policy at its history, so any member could always add a change whose history is from before the policy: judged by none, needing no signature, taken whenever it comes. Since signed values are read by `seq`, an envelope planted there with the highest `seq` there is can never be followed: a ban, a user, a declaration, for good. `--bootstrap-policy JSON`, with `--genesis`, records the policy in the genesis change, with the first users: then no change of the swarm is from before it. It must be a policy this node knows, and a strict one needs `--bootstrap-keys`, or nobody could sign what decides who may do what. --- docs/access.md | 8 +++++--- docs/example.toml | 6 ++++++ src/access/policy.rs | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ src/config/mod.rs | 19 +++++++++++++++++++ src/main.rs | 7 +++++++ src/node.rs | 4 ++++ src/simtest/mod.rs | 1 + src/state/mod.rs | 2 ++ src/swarm/bootstrap.rs | 7 ++++++- 9 files changed, 98 insertions(+), 4 deletions(-) diff --git a/docs/access.md b/docs/access.md index 2f7fa5a..89e74d7 100644 --- a/docs/access.md +++ b/docs/access.md @@ -51,8 +51,10 @@ A swarm gets a registry from its start if its genesis node is given its first us everything (`[]` and `["_continuum"]`). Other users, of its `--htpasswd` or any node's, may do nothing until added (the genesis node warns of those of its `--htpasswd`). With `--bootstrap-keys alice=ssh-ed25519\ AAAA…\ laptop` it records their keys too, so they -log in by key and sign values from the start: a swarm whose first user then writes the -policy (Values signed by their users, below) is strict from its start. +log in by key and sign values from the start, and with +`--bootstrap-policy '{"version": 1, "values": "signed"}'` the policy (Values signed by +their users, below) in the same change: the swarm is strict from its start, and no +change of it is from before the policy. Without it, the swarm has no registry: its users are all alike (A swarm without a registry, below), until someone gives it one. `--protocol-writers` counts in both: without a registry, as who may write protocol data; with one, to set it right @@ -465,7 +467,7 @@ replaced: a registry whose entries hold the users' keys turns strict as it is. A means trusted as it is: whatever entries, policy and bans it holds then count, plain values and envelopes alike, checked or not, whoever wrote them before (under a policy that isn't strict, a member may write as any user). So a swarm is best strict from its -start (`--bootstrap-keys`, A new swarm, above); one already running turns strict +start (`--bootstrap-policy`, A new swarm, above); one already running turns strict through a remake (Turning a swarm strict, below), which keeps only what an operator looked over. Writing the strict policy into it directly trusts it as it is: look it over first (`continuum-signed verify` on each entry). A value there that isn't an envelope diff --git a/docs/example.toml b/docs/example.toml index 77b9c09..3e189fe 100644 --- a/docs/example.toml +++ b/docs/example.toml @@ -150,6 +150,12 @@ htpasswd = "/etc/continuum/htpasswd" # values (docs/access.md), so a swarm can be strict from its start. # bootstrap-keys = ["alice=ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA… laptop"] +# With genesis: the swarm's write protection policy (docs/access.md), recorded in its +# first change with its first users, so that no change of the swarm is from before it: +# {"version": 1, "values": "signed"} makes it strict from its start, and needs +# bootstrap-keys. +# bootstrap-policy = '{"version": 1, "values": "signed"}' + # How log lines look: text (timestamped), journal (for systemd's journal: no timestamp or # colours, the level as each line's priority, for journalctl -p), or auto: journal when # stdout goes to the journal, else text. diff --git a/src/access/policy.rs b/src/access/policy.rs index 85b562a..9f18eb5 100644 --- a/src/access/policy.rs +++ b/src/access/policy.rs @@ -56,6 +56,36 @@ impl Policy { } } +/// The policy a new swarm records in its first change (`--bootstrap-policy`, its JSON), +/// checked: one this node knows; strict, only with its first users' keys +/// (`--bootstrap-keys`), or nobody could sign what decides who may do what. None +/// given: none. +pub(crate) fn first( + given: Option<&str>, + bootstrap_keys: &[String], +) -> Result, String> { + let Some(given) = given else { + return Ok(None); + }; + let value: JsonValue = serde_json::from_str(given) + .map_err(|error| format!("bootstrap-policy isn't JSON: {error}"))?; + let mut doc = crate::document::Document::new(); + let mut write = doc.transaction(); + store::write_path(&mut write, &path(), &value) + .map_err(|error| format!("bootstrap-policy: {error}"))?; + let policy = of(&write); + write.rollback(); + match policy { + Policy::Unknown(why) => Err(format!("bootstrap-policy: one this node doesn't know: {why}")), + Policy::Open => Err("bootstrap-policy: no policy".to_owned()), + policy if policy.strict() && bootstrap_keys.is_empty() => Err( + "bootstrap-policy: strict, but no bootstrap-keys: nobody could sign what decides who may do what" + .to_owned(), + ), + _ => Ok(Some(value)), + } +} + /// The policy `doc` holds. pub(crate) fn of(doc: &impl ReadDoc) -> Policy { let value = match store::read_plain(doc, &path()) { @@ -145,4 +175,22 @@ mod tests { )); assert!(matches!(with(json!("on")), Policy::Unknown(_))); } + + /// A new swarm's policy: one this node knows; strict, only with keys to sign. + #[test] + fn the_first_policy() { + let keys = ["alice=ssh-ed25519 AAAA".to_owned()]; + assert_eq!(first(None, &[]), Ok(None)); + assert_eq!( + first(Some(r#"{"version": 1}"#), &[]), + Ok(Some(json!({"version": 1}))) + ); + assert_eq!( + first(Some(r#"{"version": 1, "values": "signed"}"#), &keys), + Ok(Some(json!({"version": 1, "values": "signed"}))) + ); + assert!(first(Some(r#"{"version": 1, "values": "signed"}"#), &[]).is_err()); + assert!(first(Some(r#"{"version": 2}"#), &keys).is_err()); + assert!(first(Some("not json"), &keys).is_err()); + } } diff --git a/src/config/mod.rs b/src/config/mod.rs index c0abc09..1686792 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -179,6 +179,13 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[ None, "With bootstrap-users: their SSH keys, as authorized_keys lines (ssh-ed25519 [comment], named by the comment), recorded in their entries: to log in by key and sign values (docs/access.md), so a swarm can be strict from its start.", ), + option( + "bootstrap-policy", + Kind::Text, + "JSON", + None, + "With genesis: the swarm's write protection policy (docs/access.md), recorded in its first change with its first users, so that no change of the swarm is from before it: {\"version\": 1, \"values\": \"signed\"} makes it strict from its start, and needs bootstrap-keys.", + ), option( "refused-writes-per-minute", Kind::Integer, @@ -622,6 +629,7 @@ pub(crate) struct Settings { pub(crate) bootstrap_users: Vec, #[serde(default)] pub(crate) bootstrap_keys: Vec, + pub(crate) bootstrap_policy: Option, pub(crate) genesis_root: Option, #[serde(default)] pub(crate) strict_keys: Vec, @@ -898,6 +906,11 @@ impl Settings { "bootstrap-users names the first users of a new swarm; it needs genesis (drop it once the swarm exists)" ); } + if self.bootstrap_policy.is_some() && !self.genesis { + bail!( + "bootstrap-policy is the policy of a new swarm; it needs genesis (drop it once the swarm exists)" + ); + } if let Some(bad) = self .bootstrap_users .iter() @@ -910,6 +923,11 @@ impl Settings { { bail!("{why}"); } + if let Err(why) = + crate::access::policy::first(self.bootstrap_policy.as_deref(), &self.bootstrap_keys) + { + bail!("{why}"); + } if let Some(root) = &self.genesis_root && crate::swarm::roots::parse(root).is_none() { @@ -1075,6 +1093,7 @@ impl Settings { ("protocol-writers", !self.protocol_writers.is_empty()), ("bootstrap-users", !self.bootstrap_users.is_empty()), ("bootstrap-keys", !self.bootstrap_keys.is_empty()), + ("bootstrap-policy", self.bootstrap_policy.is_some()), ("alias", self.alias.is_some()), ("dashboard-url", self.dashboard_url.is_some()), ("debug-api", self.debug_api), diff --git a/src/main.rs b/src/main.rs index d8704a0..5f2403e 100644 --- a/src/main.rs +++ b/src/main.rs @@ -105,6 +105,12 @@ async fn main() -> Result<()> { } else { Default::default() }; + let first_policy = if args.genesis { + access::policy::first(args.bootstrap_policy.as_deref(), &args.bootstrap_keys) + .map_err(anyhow::Error::msg)? + } else { + None + }; if !first_users.is_empty() && let Some(path) = args.htpasswd.as_deref() { @@ -283,6 +289,7 @@ async fn main() -> Result<()> { swarm_key, protocol_writers: args.protocol_writers.iter().cloned().collect(), first_users, + first_policy, node_key: Some(Arc::clone(&node_key)), sign_every: args.sign_every, token_lifetime: args.token_lifetime, diff --git a/src/node.rs b/src/node.rs index 0744206..e5c68e0 100644 --- a/src/node.rs +++ b/src/node.rs @@ -66,6 +66,9 @@ pub(crate) struct NodeConfig { /// (`access::registry::first_users`); empty elsewhere, and where none were named /// (the simulations: no registry). pub(crate) first_users: crate::access::registry::FirstUsers, + /// On a genesis node: the swarm's policy, which it records with its first users + /// (`access::policy::first`); none elsewhere. + pub(crate) first_policy: Option, /// To sign the tokens this node issues (`access::token`) and the changes it commits /// (`document::signatures`): every node's, its node ID being its public key; none in /// the simulations without the identity layer, whose node IDs are names. @@ -183,6 +186,7 @@ impl Node { blobs: Arc::new(swarm::blob::Blobs::new(config.blob_chunk_bytes)), protocol_writers: Arc::new(config.protocol_writers), first_users: Arc::new(config.first_users), + first_policy: config.first_policy, node_key: config.node_key, sign_every: config.sign_every, screening: Arc::new(std::sync::Mutex::new( diff --git a/src/simtest/mod.rs b/src/simtest/mod.rs index 8d6437a..40f2244 100644 --- a/src/simtest/mod.rs +++ b/src/simtest/mod.rs @@ -215,6 +215,7 @@ impl Sim { swarm_key: None, protocol_writers: HashSet::new(), first_users: Default::default(), + first_policy: None, // Under the identity layer, its key signs as a node's does. node_key: self.identity.then(|| Arc::new(sim_key(id))), sign_every: Default::default(), diff --git a/src/state/mod.rs b/src/state/mod.rs index 601febc..f7c5266 100644 --- a/src/state/mod.rs +++ b/src/state/mod.rs @@ -145,6 +145,8 @@ pub(crate) struct AppState { pub(crate) protocol_writers: Arc>, /// The swarm's first users, recorded by a genesis node (`NodeConfig::first_users`). pub(crate) first_users: Arc, + /// The swarm's policy, recorded by a genesis node (`NodeConfig::first_policy`). + pub(crate) first_policy: Option, /// Signs the tokens this node issues and the changes it commits /// (`NodeConfig::node_key`). pub(crate) node_key: Option>, diff --git a/src/swarm/bootstrap.rs b/src/swarm/bootstrap.rs index 5c3b5ef..aa6d06b 100644 --- a/src/swarm/bootstrap.rs +++ b/src/swarm/bootstrap.rs @@ -110,11 +110,16 @@ pub(crate) async fn bootstrap(state: &AppState, seeds: &[String], start: Start) (crate::access::registry::user_path(name), entry) }) .collect(); + // Its policy too: no change of the swarm is then from before it. + let policy = state.first_policy.clone(); state .mutate_doc(move |doc| { for (path, entry) in &users { store::write_path(doc, path, entry)?; } + if let Some(policy) = &policy { + store::write_path(doc, &crate::access::policy::path(), policy)?; + } store::write_path(doc, &swarm_id_path(), &recorded)?; store::write_path( doc, @@ -130,7 +135,7 @@ pub(crate) async fn bootstrap(state: &AppState, seeds: &[String], start: Start) }) .await .context( - "Recording the swarm ID, its neighbours, its topology and dissemination, its first users", + "Recording the swarm ID, its neighbours, its topology and dissemination, its first users and policy", )?; if let Some(root) = crate::swarm::roots::own(state).await { info!(root = %root, "The swarm's root: a node joining may be given it (--genesis-root), to take no other"); -- cgit v1.3.1