From fc6c7101cdb42666c1f79df4206029c7cf7e61c6 Mon Sep 17 00:00:00 2001 From: tv Date: Thu, 19 Nov 2026 20:06:05 +0000 Subject: federated nodes: users who read the federation alone (--store-readers) On a federated node, every user its htpasswd or proxy lets in may do everything: put events, have it drop what it took, vote through it with its party's key, make fork roots, read the document. An application or someone watching needn't act for the node. `--store-readers USER,...` names users who read the federation and do nothing else (`api::access::federated`, before the registry's checks): GET and HEAD of the events API (/events and below), checking a fork (POST /events/fork), and keeping a session (whoami, refresh, logout); anything else is 403, saying so. Its other users are its operators, as all were: a node setting nothing changes nothing. --- src/api/access.rs | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/config/mod.rs | 14 ++++++++++ src/lib.rs | 4 +++ src/node.rs | 3 +++ src/simtest/mod.rs | 1 + src/state/mod.rs | 4 +++ 6 files changed, 104 insertions(+) (limited to 'src') diff --git a/src/api/access.rs b/src/api/access.rs index 9157e1d..47e24ba 100644 --- a/src/api/access.rs +++ b/src/api/access.rs @@ -340,6 +340,10 @@ pub(crate) async fn authorize( else { return error_response(StatusCode::UNAUTHORIZED, "not authenticated", None); }; + #[cfg(feature = "federation")] + if let Some(refused) = federated(&state, &request, &user) { + return refused; + } let access = { let replica = state.doc.read().await; if !registry::exists(&replica.doc) { @@ -389,6 +393,54 @@ pub(crate) async fn authorize( next.run(request).await } +/// On a node holding a federated store, what its users who aren't its operators may do: a +/// user of `--store-readers` reads the federation (`federation_work`), and nothing else. +/// Its other users are its operators, who may do everything. The answer refusing the +/// request, where it is refused. +#[cfg(feature = "federation")] +fn federated(state: &AppState, request: &Request, user: &str) -> Option { + if !state.store_readers.contains(user) { + return None; + } + if state.holding.with(|_| ()).is_none() { + return Some(error_response( + StatusCode::FORBIDDEN, + format!("{user} reads a federated store here alone, and this node holds none"), + None, + )); + } + if federation_work(request.method(), request.uri().path(), false) { + return None; + } + debug!(user = %user, method = %request.method(), path = %request.uri().path(), "Refused a reader's request that doesn't read the federation"); + Some(error_response( + StatusCode::FORBIDDEN, + format!( + "{user} reads the federation here, and does nothing else (--store-readers; \ + docs/guides/federation/running-a-node.md, Its API)" + ), + None, + )) +} + +/// Whether a request is federation work: reading the events API (`GET` and `HEAD` of +/// `/events` and below), checking a fork (`POST /events/fork`), and keeping a session +/// (`GET /auth/whoami`, `POST /auth/refresh`, `POST /auth/logout`); with `puts`, putting +/// an event (`POST /events`) too. Nothing of the document (`/store`, `/stream`), the +/// node (`/peers`, `/admin/…`), nor what a node's operator does to its store +/// (`/admin/events/…`). +#[cfg(feature = "federation")] +fn federation_work(method: &Method, path: &str, puts: bool) -> bool { + let reads = matches!(*method, Method::GET | Method::HEAD); + let posts = *method == Method::POST; + match path { + "/auth/whoami" => reads, + "/auth/refresh" | "/auth/logout" | "/events/fork" => posts, + "/events" => reads || (puts && posts), + _ => reads && path.starts_with("/events/"), + } +} + #[cfg(test)] mod tests { use super::*; @@ -402,6 +454,32 @@ mod tests { .collect() } + /// Federation work is reading the events API, checking a fork and keeping a session; + /// putting events where it puts; nothing of the document, the node, or what an + /// operator does to the store. + #[cfg(feature = "federation")] + #[test] + fn federation_work_is_the_events_api() { + let work = |method: Method, path: &str, puts: bool| federation_work(&method, path, puts); + assert!(work(Method::GET, "/events", false)); + assert!(work(Method::GET, "/events/counts", false)); + assert!(work(Method::HEAD, "/events/0c7e", false)); + assert!(work(Method::POST, "/events/fork", false)); + assert!(work(Method::POST, "/auth/refresh", false)); + assert!(work(Method::GET, "/auth/whoami", false)); + assert!(!work(Method::POST, "/events", false)); + assert!(work(Method::POST, "/events", true)); + assert!(!work(Method::POST, "/admin/events/drop", true)); + assert!(!work(Method::POST, "/admin/events/vote", true)); + assert!(!work(Method::GET, "/admin/events/fork", true)); + assert!(!work(Method::GET, "/store", true)); + assert!(!work(Method::GET, "/store/home/tv", true)); + assert!(!work(Method::GET, "/stream", true)); + assert!(!work(Method::GET, "/peers", true)); + assert!(!work(Method::GET, "/eventsx", true)); + assert!(!work(Method::PUT, "/events/0c7e", true)); + } + /// A token's limit narrows what an endpoint takes, not only what the store's handlers /// read: the dashboard's hand-over token (the member list, read) of an operator may /// look, and nothing else. diff --git a/src/config/mod.rs b/src/config/mod.rs index ea15e06..0b6a58a 100644 --- a/src/config/mod.rs +++ b/src/config/mod.rs @@ -241,6 +241,14 @@ pub(crate) const OPTIONS: &[OptionSpec] = &[ "With store-root or store-id, which need it: the party this node is of (docs/store.md, Members), named in its entry and its handshakes. Nodes of a swarm holding a store sync with the nodes its parties list, each as its party's, and with no others.", ), #[cfg(feature = "federation")] + option( + "store-readers", + Kind::List, + "USER,[USER...]", + None, + "With store-root or store-id: users of this node's HTTP API (htpasswd, user-header) who read the federation here and do nothing else: GET of the events API, and fork checks (docs/guides/federation/running-a-node.md, Its API). Its other users are its operators, who may do everything.", + ), + #[cfg(feature = "federation")] option( "store-neighbour-parties", Kind::List, @@ -819,6 +827,9 @@ pub(crate) struct Settings { pub(crate) store_party: Option, #[cfg(feature = "federation")] #[serde(default)] + pub(crate) store_readers: Vec, + #[cfg(feature = "federation")] + #[serde(default)] pub(crate) store_neighbour_parties: Vec, #[cfg(feature = "federation")] pub(crate) store_vote_key: Option, @@ -1340,6 +1351,7 @@ impl Settings { ("store-file", self.store_file.is_some()), ("store-checkpoint", self.store_checkpoint.is_some()), ("store-party", self.store_party.is_some()), + ("store-readers", !self.store_readers.is_empty()), ( "store-neighbour-parties", !self.store_neighbour_parties.is_empty(), @@ -1491,6 +1503,8 @@ impl Settings { #[cfg(feature = "federation")] ("store-party", self.store_party.is_some()), #[cfg(feature = "federation")] + ("store-readers", !self.store_readers.is_empty()), + #[cfg(feature = "federation")] ( "store-neighbour-parties", !self.store_neighbour_parties.is_empty(), diff --git a/src/lib.rs b/src/lib.rs index 28d18e5..a2e24ba 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -346,6 +346,10 @@ pub async fn run() -> Result<()> { blob_chunk_bytes: args.blob_chunk as u32, swarm_key, protocol_writers: args.protocol_writers.iter().cloned().collect(), + #[cfg(feature = "federation")] + store_readers: args.store_readers.iter().cloned().collect(), + #[cfg(not(feature = "federation"))] + store_readers: Default::default(), first_users, first_policy, node_key: Some(Arc::clone(&node_key)), diff --git a/src/node.rs b/src/node.rs index 22aa0df..6fc8c66 100644 --- a/src/node.rs +++ b/src/node.rs @@ -62,6 +62,8 @@ pub(crate) struct NodeConfig { pub(crate) blob_chunk_bytes: u32, pub(crate) swarm_key: Option>, pub(crate) protocol_writers: HashSet, + /// `--store-readers`: on a node holding a federated store, the users who only read it. + pub(crate) store_readers: HashSet, /// On a genesis node: the swarm's first users, which it records /// (`access::registry::first_users`); empty elsewhere, and where none were named /// (the simulations: no registry). @@ -193,6 +195,7 @@ impl Node { blobs: Arc::new(swarm::blob::Blobs::new(config.blob_chunk_bytes)), speaking: Arc::default(), protocol_writers: Arc::new(config.protocol_writers), + store_readers: Arc::new(config.store_readers), first_users: Arc::new(config.first_users), first_policy: config.first_policy, node_key: config.node_key, diff --git a/src/simtest/mod.rs b/src/simtest/mod.rs index c96f189..d0f80da 100644 --- a/src/simtest/mod.rs +++ b/src/simtest/mod.rs @@ -216,6 +216,7 @@ impl Sim { blob_chunk_bytes: 64 * 1024, swarm_key: None, protocol_writers: HashSet::new(), + store_readers: HashSet::new(), first_users: Default::default(), first_policy: None, // Under the identity layer, its key signs as a node's does. diff --git a/src/state/mod.rs b/src/state/mod.rs index cbdc509..68eafec 100644 --- a/src/state/mod.rs +++ b/src/state/mod.rs @@ -145,6 +145,10 @@ pub(crate) struct AppState { /// HTTP API users who may write protocol data through the store API /// (`--protocol-writers`). pub(crate) protocol_writers: Arc>, + /// HTTP API users who only read the federated store this node holds + /// (`--store-readers`, `api::access::federated`). + #[cfg_attr(not(feature = "federation"), allow(dead_code))] + pub(crate) store_readers: 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`). -- cgit v1.3.1